Print server presentation and operation guide

The SAFE X3 print server is a logical component of a "server" type intended to process, in a concurrent manner, the print requests coming from the different entities of one or more SAFE X3 solutions.

The print server is a "multiprocessing" server. Depending on the global system availability, each print request saved at the server level is addressed to a dedicated print process. The dedicated processes are under the control of the print server.
At any moment, the entity that has submitted a request may ask the print server to either recover the current status of the request, modify certain attributes, or delete the submitted request.

The following table shows the different sections of this document:

Installation / Uninstallation

Prerequisites

Before starting the installation of a print server on a machine, verify the Prerequisites documentation.

Installation

The installation program allows you to place (in the folder of your choice) the executables, libraries, and other resources that are necessary for the correct execution of the print server.

After placing the files, the following tree structure is created in the installation folder:

• The Root folder contains all the server binary codes.

• The "Config" folder contains a set of files in XML format. It is very important that these files are never updated manually. They 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. These files are used:

  • During the 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).

• The "Data" folder contains all the files of the internal server cache. Among others, the "Crystal Report" reports coming from the SAFE X3 applications attached to the server are stored in the server cache.

• The "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").

• The "Lan" folder contains the localization files. If required, these files are updated during patch list installations.

• The "Temp" folder collects the temporary files. It must be emptied regularly, depending on its volume (Warning: the server has to be stopped when emptying the folder).

• The "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 by using the "Add/Remove programs" from the control panel of your server, it is first necessary to have unpublished the SAFE X3 solutions attached to the print server by using the SAFE X3 administration console.

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 documentation for the administration console. The information related to the print server configuration is presented below.

Startup setup

These parameters are used to configure the technical execution environment of the print server. They are stored in the "adxeditionserverconfig.xml" file in the "Config" folder.

These parameters include:

• The operating language code: It is in this language that the server displays any messages. Regardless of this language code, the print server is able to print multilanguage reports.

• The TCP/IP listening port number: This parameter is used to set the port number that the print server should use to listen to incoming connections.

• The size of the printing requests stack: This parameter is used to set the maximum number of requests that can be stacked by the print server. This parameter must be adjusted according to the maximum current load of the print server.

• The maximum number of processes: This parameter is used to set the maximum number of print processes that the print server is authorized to launch in parallel. This parameter must be adjusted according to 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 has an "available" status.

• The characteristics of the server activity and exception log files: It 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 of setting the number of archive volumes of the log file and the maximum limit size (number of bytes) of these volumes. 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 upon server start), the archive volumes are swapped to free a volume and thus archive the current volume.
  Note that the activity log stores events such as the "saving", "submission", "end", and "deletion" of a print request. The exception log stores all of the errors and anomalies detected by the server.

• Setup of "Recovery" mode: It is 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 the paragraph "The server startup options" - option "Recovery:status".

• Shared memory size: This document describes how the print server uses shared memory segments to exchange data with its print processes. As the shared memory segments cannot be dynamically extended, the maximum size of these segments must be set upon a server startup. If the size allocated at startup (by this parameter) is not sufficient for the standard use context, the print server displays an error identified by the code 266. If this error code is issued, you need to stop the server, modify the value of this parameter (VPALLOC) through the SAFE X3 administration console, and then restart the server. The default value assigned to this parameter ("40", which corresponds to a multiplier coefficient in relation to a ratio based on the maximum size of the request stack) 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 parameters for the description of the SAFE X3 solutions attached to the print server are stored in the "adxeditionserversolutions.xml" file in the "Config" subfolder. This XML description file is updated by the SAFE X3 administration console following the publication of a solution.

Only a print request coming from a SAFE X3 technology application belonging to a published solution can be processed by the print server.

The file for the solution description has a tree structure that makes it possible to describe:

• A solution profile. This notion is reserved for future use. Currently, only the "ADMIN" profile code is used.
• For each profile, there is a 1 to N associated solutions.
• For each solution, there is the description of:
  • 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 may add/modify the REG_DWORD registry entry described below, with a suitable value :

• Availabilty : EDT.208 or higher
• Description : control 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 : TCP port is registered in "etc/services" file, and ODBC source is created as "System" DSN
  • 1 : TCP port is not longer registered in "etc/services" file.
  • 2 : ODBC source is created as "User" DSN
  • 3 : Combination of values 1 and 2. It means that's with this setting, print server Windows service can be run with a non-administrator user
  • Default value : 0
  • Warning : in order to allow the print server to run with non-administrator user, this registry sub key with value 3 must be created before to configure the component through the administration console.

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

• Availabilty : EDT.102 or higher
• Description : turn on/off debug mode for 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 file "%TEMP%\u212ltext.log"
  • Default value : OFF

Server startup / stop

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

During the first server configuration from the SAFE X3 administration console, the console automatically creates a "Windows Service" by default associated with the server. It is possible to start and stop this service by the administration console. Nothing prevents the use of the standard tools in the Windows system to administer and control the service created in this manner.

The print server startup options are described below. It should be noted that these are available both in "Console" mode and "Windows Service" mode.

The print server startup options are the following:

• Launching of the server in Recovery mode: "/recovery:status": In case of an unexpected shutdown of a print server during processing (for example, shutdown of the Windows services upon immediate shutdown procedure of a workstation), the stack of pending print requests or print requests under 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. Thus, the print requests that have aborted 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 (whether activated or not).
  Note that this option can be used to force the "Recovery" policy set up in the administration console:

  • To force the activation of the "Recovery" mode, set the value status to 1.
  • To force the deactivation of the "Recovery" mode", set the value status to 0.

• Activation of the log file: " /d": This option is used to produce a file that logs the activity of the print server and of the printing processes that are launched. The produced file is named "AdxSrvlmp_Trace.log"; it is stored in the temporary folder of the print server.
  This option must be used if problems occur, to facilitate the analysis and correction of 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 service mode.

• Deactivating the control and configuration of the ODBC sources: "/noodbc": When it is launched with this option, the print server does not manage the creation, the control, and the configuration of the ODBC data sources that it will use to connect to the data servers of the SAFE X3 solutions linked to it. The user should create and correctly configure the ODBC data sources, based on the characteristics of the different SAFE X3 solutions attached to the server.

• Launching using a configuration profile different from the default profile: " /cfg:cdprofil": Reserved for future use.

• Deletion of a Windows service created previously: "/rmsvc:cdservice": After deleting the required service, the print server automatically stops.

• Display of the print server version: "/v": Available only in Console mode.

Monitoring

Even if the server has not been started with the "/d" log file option, it is possible to follow its activity by consulting the activity log file or the Windows Events Viewer, and by accessing the "Print Monitor" function available in each SAFE X3 folder.

Monitoring window

To display this window, it is necessary to connect, in Classic mode, to the print monitor function (PSIMP). Entering the name and port of the print server allows you to display related data to the server activity.

From this screen, you can:
* View the server startup parameters (Configuration section).
* View the current TCP/IP sessions (Connected clients section).
* View and potentially modify the parameters associated with the requests that are either stacked or being executed (Task section).

Activity log file and exception log file

The activity log file records the "saving", "submission", "termination", and "deletion" events related to a print request.

The exception log file records all the errors or anomalies detected by the server.

These log files are activated and set up by the server administration console (refer to the "Configuration" module - the exception log file automatically inherits the setup of the activity log file).
A log file is subdivided into volumes. Each volume is physically associated with a file stored in the server "Log" subfolder.

When the current volume has reached its maximum size (or upon server start), the archive volumes are swapped to free a volume and thus archive the current volume.

Windows Events Viewer

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

In case of incidents, you should take a look at the Events Viewer to establish a detailed diagnosis (AdxSrvImp and AdxImp sources).

Technical architecture

The diagram below represents the simplified technical architecture for the print server.

Principles

As indicated before, the print server is a "multiprocess" server. It maintains and controls a "pool" of specialized processes that have as their only function the production of Crystal Report reports. 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:

• The TCP/IP listening service: Whenever a client sets up a TCP/IP connection to the print server service, it creates a "Client Thread " that is dedicated to the management of the request coming from this client. At a given moment, there will be as many "Client Threads" as connected clients.

• The technological services: These services ensure the integrity of the server and mainly control the access to the shared resources (see below). In addition, a specialized technical service 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 the Oracle data sources, the print server supports versions 9, 10, and 11 of the OracleNet client and 'Wire Protocol' type ODBC Oracle drivers. The user account under which the print server is launched must have sufficient rights and privileges to create the ODBC system data sources and the OracleNet aliases. The user can, if required, manually create the ODBC data sources by using the startup option "/noodbc" (see the print server startup options).

• The basic services: The print server processes a certain number of basic functional services. Below is the list of the main functional services:

  • Saving and formatting the parameters associated with a print request.
  • Printer selection.
  • Printer configuration.
  • Monitoring of requests in progress.

• The files transfer: The management of a print request coming from a SAFE X3 application often requires the loading of files stored in this application (for example, the ".rpt" report file). The print server operates with SAFE X3 (SADFSQ) file servers. The print server needs to communicate with these file servers establishing a TCP/IP connection with the corresponding application servers that are associated with it.

• The print processes: When the print server is finished preparing a print request (the entry of the parameters, file transfers necessary for the printing, and so forth), and depending on the system availability, it launches a print process that will manage the final production of the report. The main task of this print process is to initialize and call the Crystal Report print engine. It is the latter that actually produces the requested report.
  
  After completing the report processing, a print process accesses the shared memory of the print server to determine if the server has pending print requests. If this is the case, the print process 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: As indicated above, 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

The following rules must be followed for the print server to carry out the printing operation correctly:

• If the print server is started in "Windows service" mode, it is absolutely necessary 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.
• The user account with which the print server has been started (in "Console" or "Windows service" mode) must have at least one printer set up.
• The print server will only be able to address printers that are "visible" and "accessible" to the user account under which the server was started (whether in "Console" or Windows service" mode).
• If printing with the generation of a document in the PDF format, the parameters relating to the document size will be inherited from the default paper size of the printer associated with the user account under which the server was started (whether in "Console" or Windows service" mode).

Error codes and messages

The error codes generated by the print server are referenced below. They are sorted by category.

The formatted 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 from which the error came.
• The context, with a character string giving the detail information.

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