January 2007 (Version 6.3 and later)
This document applies to ScriptX Printing v6.3.434.26 or later. If you are using an earlier version, please visit the MeadCo web site for an upgrade.
The standard install of ScriptX utilises standard COM object installation and registration. Most components are in-process (Security Manager and the ScriptX Factory object) with printing carried out by an out-of-process component (MeadCo TriPrint Server). This scheme works well and is described in the standard Server side deployment notes. The standard install can be tricky to get working, depending upon the security configuration of the host system and it will not work on x64 systems because ScriptX consists entirely of 32bit components.
This document describes how to create a COM+ application for hosting the ScriptX components. This may prove a useful alternative configuration for x32 server systems and is a required technique for x64 server systems. For x64 systems, the COM+ application acts as an out-of-process host for the 32 bit components, the 64 bit IIS can then communicate with the components across this bridge.
Please note that all the caveats for server side printing described in the standard Server side deployment notes still apply; the use of a COM+ application wrapper in no way mitigates these issues. Please read through all the standard Server side deployment notes to gain an overview of the function of ScriptX server side.
The Component Services Management Console is used for the creation and management of a COM+ applications - this document assumes familiarity with this tool.
Windows Vista
Under Windows Vista, the Component Services Management Console is not available on the Administrative Tools menu. To access Component Services:
- Start the Microsoft Management Console by using a Run box or command prompt and type mmc
- From the File Menu, select Add or Remove Snap-in...
- From the list of available snap-ins, select Component Services.
- Recommended; from the File Menu, select Save and save the console with a suitable name - it can then be loaded again at another time, or double clicked to start the console.
After completing these configuration sets, ScriptX will not be usable from within client-side Internet Explorer.
Windows XP, Windows Server 2000, Windows Server 2003 and Windows Vista are supported.
A license from MeadCo is required to enable server-side printing.
It is strongly recommended that an evaluation license is obtained from MeadCo and a suitable server set aside for testing and evaluation - installation and configuration of the components may require several re-boots in order to achieve the settings required in a particular scenario. Following successful test deployment and evaluation, the set of steps and/or configurations necessary for deployment to production servers within your environment/scenario should have been determined.
The license and software package will be supplied as a .zip file containing the installer for the latest version of the software (smsx.exe) and an installer for the license (sxlic.hta and sxlic.mlf). You will also be supplied with your unique license identifier (GUID) and revision.
To install the software, both these applications must be run (smsx.exe and sxlic.hta) while logged onto an account with administrator privileges. Administrator privileges are required since the installers write to the HKEY_LOCAL_MACHINE hive and the software is installed in the Windows system directory (if this is not acceptable, please consider installation of the Zeepe framework; the Zeepe framework contains the ScriptX feature set but is more flexible as to its installation requirements).
Please note that the license must be installed before configuring ScriptX as a COM+ application.
ScriptX should be installed using the usual mechanisms, see above, before configuration within a COM+ application - this will create all the required registry entries for correct operation of ScriptX. Once installed, the following steps should be used:
The Component Services console will now list the newly created application.
That completes initial configuration.
Printing with ScriptX configured in this way is handled in the same way as described in the standard Server side deployment notes:
For example:
<%
' Apply licensing - the license must already be installed.
set secmgr = CreateObject("MeadCo.SecMgr")
secmgr.Apply "","{XXXX-XXXX-XXXX-XX}",1
' the object is dynamically created and destroyed
set factory = CreateObject("ScriptX.Factory")
factory.printing.header = "Report printed on the server"
factory.printing.footer = "Printed on &D"
factory.printing.PrintHTML "http://localhost/orders/order.asp?number=" & Request.Form("number")
' After use, shut down the object to ensure that resources
' are released in a timely manner
factory.ShutDown
set factory = nothing
%>
A number of test and sample files are available as a .zip archive, we recommend you download these (click here) and unpack the archive to a suitable location.
ASP.NET If you intend to use ScriptX Printing with ASP.NET we recommend that you first configure and test the system using the old form Active Server Pages (.asp files). There are a number of additional considerations when working with ASP.NET that further complicate configuration - using .asp files reduces the number of potential causes of failure.
After unpacking the files, please modify each .js, .asp and .aspx file to use the GUID and revision supplied to you; the modifications required are clearly sign-posted in each file.
This test should be undertaken after software and license installation and COM+ application configuration, but before any further configuration to validate the installation of the license and the basic operation of the software. Please note that this same test can be repeated at any time after software configuration and is a simple "sanity check" on the software.
Note
Some errors from any of the following installation and configuration processes can leave apparently orphaned processes. These processes do eventually shutdown but it can take some time (of the order of 5 minutes). Any MCPXHost process that appears will be due to ScriptX - it is safe to end these processes using task manager. Finally, the running COM+ application can be stopped to force unloading of all the components.
Open a "Command Prompt", change to the directory to which the sample files were unpacked and enter the following command:
cscript validate.js
Potential errors and their resolution:
| Error | Possible cause/action |
| The system cannot find the file specified. | The license is not installed. Double check that the
GUID listed in validate.js is correct. Run "License Manager" from the
"Mead & Company" item on the "All Programs" start menu - your server
license should be listed. If not, try to install the license again using
the supplied sxlic.hta. Please note that the license must be listed in the Machine Licenses (Available to all users) section. |
| Invalid HTML parameters specified for the license. | The license revision number listed in validate.js is incorrect. |
| Permission denied | The DCOM configuration of your server does not allow the interactive account to launch/access local COM server processes (there may also be a DCOM event in Event viewer) |
| PageSetup/Print Dialog system error: 00001008 | There is no default printer for the account. |
Successful completion of this test illustrates that the ScriptX components and the license are correctly installed on the machine and are working properly.
Subsequent tests will lead you through the configuration of ScriptX and validation that the use of ScriptX is functioning satisfactorily with your server environment, either ASP or ASP.NET.
As previously stated, these steps require a solid understanding of the security policies applied to the server and their configuration. Whilst these steps will be satisfactory for most scenarios, Microsoft are, quite rightly, shipping their servers with ever more secure environments; these steps assume that the SYSTEM account is allowed to perform DCOM activations and access. This may not be true for your system. If this is so, please read all of the following sections and apply configuration changes as they are required for your environment.
Important
ScriptX uses the COM Local Server "MeadCo TriPrint Server"; this is the object that must be satisfactorily configured using the "Component Services" Admistrators tool (DComCnfg.exe). Whatever the evironment - ASP or ASP.NET, or simply the interactive account (for validate.js) - the COM+ Application hosting ScriptX must be accessible (by default, it will run under the Interactive account) and it must be able to both launch and access this component (by default, it too will run under the Interactive account). Please note that Windows XP SP2 and Windows Server 2003 SP1 have introduced more granular control of DCOM permissions allowing the separation of control of local and remote launch/access. ScriptX should only be configured for local launch/access.
The following steps should be undertaken whilst logged onto the server machine under an account with Administrator privileges. The samples listed are available in the zip archive previously mentioned.
For IIS 6 (Windows Server 2003), create an application pool for use by virtual directories/sites that will use the ScriptX components.
<%@ LANGUAGE="VBScript"%>
<%
Response.Expires = 0
%>
<HTML>
<HEAD><TITLE>ScriptX Printing Server Test 1</TITLE></HEAD>
<BODY>
<H1>Testing ScriptX Printing.</H1>
<h3>You are logged in as: [<%= Request.ServerVariables("LOGON_USER")%>] at: <%= Now %></h3>
<%
dim factory,p,secMgr
dim a,b,c,d
Set secMgr = Server.CreateObject("MeadCo.SecMgr")
on error resume next
' Modify:: Change the following to use the license GUID and
' revision supplied to you.
'
secMgr.Apply "","{761F1FE3-DD98-4F4F-9C17-0338ACFDA356}",4
if err.Number <> 0 then
Response.Write "Unable to apply license: " & err.description & " (Error code: " & err.Number & ")"
else
Set factory = Server.CreateObject("ScriptX.Factory")
factory.GetComponentVersion "ScriptX.Factory",a,b,c,d
Response.Write("ScriptX version installed: " & a & "." & b & "." & c & "." & d & "<br>")
set p = factory.printing
if err.Number <> 0 then
Response.Write "Unable to access printer object - there is a ScriptX configuration error. Error on create: " & err.description & " (Error code: " & err.Number & ")"
else
b = p.IsSpooling
if err.Number <> 0 then
Response.Write "Printing is not licensed: " & err.description & " (Error code: " & err.Number & ")"
else
Response.Write "Printing is licensed"
end if
end if
end if
set p = nothing
factory.ShutDown
set factory = nothing
set secMgr = nothing
%>
</BODY>
</HTML>
Navigate to the page using Internet Explorer and verify that the page is displayed without errors and that printing is licensed. This test ensures that the ScriptX components are correctly installed and the license is available.
Note: If the above test fails with a 0113 error (Script timed out), it is most likely that Application Protection is not set to Low (IIS Process) on the virtual directory.
If the error "Permission denied" is received, then your DCOM configuration is not allowing launch of the "MeadCo TriPrint Server" by the SYSTEM account. If the error "Access denied" is received, then your DCOM configuration is not allowing access to the launched "MeadCo TriPrinter Server" object.
<%@ LANGUAGE="VBScript"%>
<%
Response.Expires = 0
%>
<HTML>
<HEAD><TITLE>ScriptX Printing Server Test 2</TITLE></HEAD>
<BODY>
<H1>Testing ScriptX Printing.</H1>
<%
dim factory,p,secMgr
dim a,b,c,d
Set secMgr = Server.CreateObject("MeadCo.SecMgr")
on error resume next
' Modify:: Change the following to use the license GUID and
' revision supplied to you.
'
secMgr.Apply "","{9a248c3a-b8c9-11d3-b934-002018654e2e}",17
if err.Number <> 0 then
Response.Write "Unable to apply license: " & err.description & " (Error code: " & err.Number & ")"
else
Set factory = Server.CreateObject("ScriptX.Factory")
set p = factory.printing
if err.Number <> 0 then
Response.Write "Unable to access printer object - there is a ScriptX configuration error. Error on create: " & err.description & " (Error code: " & err.Number & ")"
else
Response.Write "The default printer is: " & p.DefaultPrinter() & "<br>"
if err.Number <> 0 then
Response.Write "No default printer available: " & err.description & " (Error code: " & err.Number & ") - a default printer is required."
else
Response.Write "The page headers are: " & p.header & "<br>"
p.header = "ScriptX Printing - Printing at the Server"
Response.Write "The updated page headers are: " & p.header & "<br>"
Response.Write "The printer is: " & p.printer & "<br>"
if err.Number <> 0 then
Response.Write "There is a ScriptX configuration error: " & err.description & " (Error code: " & err.Number & ")"
end if
end if
end if
end if
set p = nothing
factory.ShutDown
set factory = nothing
set secMgr = nothing
%>
</BODY>
</HTML>
Navigate to the page using Internet Explorer and verify that the page is displayed without errors. This test ensures that the ScriptX components are correctly installed and the default printer for the current interactive account is accessible.
<%@ LANGUAGE="VBScript"%>
<%
Response.Expires = 0
%>
<HTML>
<HEAD><TITLE>ScriptX Printing Server Test 3</TITLE></HEAD>
<BODY>
<H1>Testing ScriptX Printing.</H1>
<%
dim factory,p,secMgr
dim a,b,c,d
Set secMgr = Server.CreateObject("MeadCo.SecMgr")
on error resume next
' Modify:: Change the following to use the license GUID and
' revision supplied to you.
'
secMgr.Apply "","{9a248c3a-b8c9-11d3-b934-002018654e2e}",17
if err.Number <> 0 then
Response.Write "Unable to apply license: " & err.description & " (Error code: " & err.Number & ")"
else
Set factory = Server.CreateObject("ScriptX.Factory")
set p = factory.printing
if err.Number <> 0 then
Response.Write "Unable to access printer object - there is a ScriptX configuration error. Error on create: " & err.description & " (Error code: " & err.Number & ")"
else
p.header = "ScriptX Printing - Printing at the Server"
p.footer = "Printed at the server"
p.printHTML "http://localhost/default.htm" ' Change this URL to an appropriate page on your server.
if err.Number <> 0 then
Response.Write "Printing failed: " & err.description & " (Error code: " & err.Number & ")"
else
Response.Write "<p>The page has been printed.</p>"
end if
end if
end if
set p = nothing
factory.ShutDown
set factory = nothing
set secMgr = nothing
%>
</BODY>
</HTML>
Navigate to the page using Internet Explorer and verify that the page is displayed without errors. This test ensures that the ScriptX components are correctly installed and the default printer for the current interactive account is accessible and printing to the printer.
Note: If the above test fails with "Unspecified error" the most likely cause is that a valid printer is not available and cannot be accessed.
<%@ LANGUAGE="VBScript"%>
<%
Response.Expires = 0
%>
<HTML>
<HEAD><TITLE>ScriptX Printing Server Test 4</TITLE></HEAD>
<BODY>
<H1>Testing ScriptX Printing with MaxiPT.</H1>
<%
dim factory,p,secMgr,maxpipt
dim a,b,c,d
Set secMgr = Server.CreateObject("MeadCo.SecMgr")
on error resume next
' Modify:: Change the following to use the license GUID and
' revision supplied to you.
'
secMgr.Apply "","{9a248c3a-b8c9-11d3-b934-002018654e2e}",17
if err.Number <> 0 then
Response.Write "Unable to apply license: " & err.description & " (Error code: " & err.Number & ")"
else
Set factory = Server.CreateObject("ScriptX.Factory")
Set maxipt = CreateObject("MeadCo.MaxiPT")
set p = factory.printing
if err.Number <> 0 then
Response.Write "Unable to access printer object - there is a ScriptX configuration error. Error on create: " & err.description & " (Error code: " & err.Number & ")"
else
' Set a header and footer - note that these will be overridden
' by the printing rules specified in the document being printed.
'
p.header = "ScriptX Printing - Printing at the Server"
p.footer = "Printed at the server with MaxiPT"
' apply maxiPT template for printing rather than the standard
p.templateUrl = maxipt.Template
p.printHTML "http://localhost/testsx/maxiptout.asp" ' Change this URL to an appropriate page on your server.
if err.Number <> 0 then
Response.Write "Printing failed: " & err.description & " (Error code: " & err.Number & ")"
else
Response.Write "<p>The report has been printed."
end if
end if
end if
set p = nothing
maxipt.ShutDown
factory.ShutDown
set factory = nothing
set secMgr = nothing
%>
</BODY>
</HTML>
You will also need to create the target document to be printed (maxiptout.asp):
<%@ LANGUAGE="VBScript" %>
<%
Response.Expires = -1
Response.CacheControl = "no-cache"
call Response.AddHeader("Pragma", "no-cache")
%>
<HTML>
<HEAD>
<TITLE>MaxiPT Controlled Output</TITLE>
<script>
// This page is printed with the MaxiPT template applied to
// the process doing the printing
//
// This gives this document the opportunity to specify how it
// wants to be printed.
//
// Please see the MaxiPT documentation for full details.
//
function initialiseMaxiPT() {
document.expando = true;
document.printingRules = {
diffFirstPageHeadFoot: true,
allPagesHeadFoot: true,
pageRange: "",
printingPass: "all",
mirrorMargins: true,
setupButton: "show",
setupExtraButton: "enabled"
}
document.printingRules.extraFirstPageFooter = "<div style='border: thin inset threedface; font: 15pt Comic Sans MS; background: lavender; color: orchid'><center><b>Extra Footer</b> for the First Page</center></div>";
document.printingRules.firstPageHeader = "<div style='border: thin inset threedface; font: 15pt Comic Sans MS; background: lightskyblue; color: darkblue'><center><i>--- Header for page <b> &p </b>---</i></center></div>";
document.printingRules.firstPageFooter = "<div style='border: thin inset threedface; font: 15pt Comic Sans MS; background: lightskyblue; color: darkblue'><center><i>--- Footer for page <b> &p </b> ---</i></center></div>";
document.printingRules.allPagesHeader = "<div style='border: thin inset threedface; font: 15pt Comic Sans MS; background: antiquewhite; color: darkgreen'><center><i>--- Header for page <b> &p </b>---</i></center></div>";
document.printingRules.allPagesFooter = "<div style='border: thin inset threedface; font: 15pt Comic Sans MS; background: antiquewhite; color: darkgreen'><center><i>--- Footer for page <b> &p </b> ---</i></center></div>";
}
</script>
</HEAD>
<BODY onload="initialiseMaxiPT()">
<H1>MaxiPT with Server Side Printing Test</H1>
<p>The time at the server is: <%= Now %></p>
</BODY>
</HTML>
Navigate to the test page using Internet Explorer and verify that the page is displayed without errors. This test ensures that the ScriptX components are correctly installed and the default printer for the current interactive account is accessible and printing to the printer.
That completes the initial testing of the ScriptX installation. At the succesful completion of these tests, the software is known to be installed correctly and licensed. From here on in, all problems are to do with the security configuration of the machine.
The above steps complete the initial deployment of ScriptX Printing server side within a COM+ application and validate that ScriptX can be used successfully on the server within a COM+ application. However, as configured after initial installation, there are some undesirable aspects:
The changes listed in the following sections are those for a default install of Windows Server. If you are having problems and are doubtful that the problem is to do with DCOM settings, then add the "Everyone" account to default launch and access permissions - if this solves all the problems then it confirms that you have a DCOM security configuration problem.
Before making the changes discussed here, the running COM+ Application hosting the ScriptX components should be shutdown to ensure that the ScriptX Components are unloaded.
Application Protection
The ASP worker process will run under either the IUSR_<machinename> account (medium protection) or IWAM_<machinename> (high protection). These accounts must have "Log on as a batch job" rights.
After changing the protection level and appropriate configuration with dcomcnfg.exe it is suggested that the above tests are run again to ensure successful operation.
Note: If the tests fail with the error "Unable to create ActiveX Object" the most likely cause is that the IUSR/IWAM accounts do not have "Log on as a batch job" rights or do not have permission to launch DCOM servers.
In addition, the account used as the identity for the "MeadCo TriPrint Server" object must have DCOM access permissions, at this stage this can be achieved by adding INTERACTIVE to the Default access permissions list - however, see section 3.3 below for additional configuration.
As initially configured, the application pool is using the SYSTEM account. It is preferable to use either a default account (e.g. the default NETWORK SERVICE) or a named account created for the purpose. After changing the identity to use (e.g.) the NETWORK SERVICE account, it is almost certain that the tests listed above (start with testprint1.asp) will fail with:
"Unable to access printer object - there is a ScriptX configuration error. Error on create: Access is denied. (Error code: -2147024891)"
There will also likely be an error from DCOM in the System event log:
"Access denied attempting to launch a DCOM server, The server is: {1663ED76-23EB-11D2-B92F-008048FDD814} ..."
The account used must have permission to launch DCOM servers and access DCOM servers. "Component Services" should be used for this. It is our experience that changes to "Default COM Security" must be made, applying the changes to the "MeadCo Triprint Server" is insufficient. In otherwords, for example, add NETWORK SERVICE to those accounts listed for both Launch and Access permissions under Default COM Security.
In addition, the account used as the identity for the "MeadCo TriPrint Server" object must have DCOM access permissions. At this stage this can be achieved by adding INTERACTIVE to the Default access permissions list - however, see section 3.3 below for additional configuration.
After changing the protection level and appropriate configuration with "Component Services" it is suggested that all the above tests are run again to ensure successful operation.
Running the ScriptX Printing COM+ Application under a specific user account removes the necessity for an interactive user to be logged on to the server machine. There is no necessity for the account to be used to have "Administrator" rights. However, it must:
As discussed here: HOWTO: Configure Office Applications to Run Under a Specific User Account, if the account to be used is not already logged on, its registry hive will not be used - the "Default User" hive will be used instead. Although the default hive can be configured with access to the required printer(s), since ScriptX Printing requires read and write access to various parts of the hive (for example to store print header/footer settings) this is not recommended. It is recommended that a "null" service is used instead, as discussed in the above article. If the account to be used for ScriptX Printing is not already in use for a service, a suitable service is available here: Service.zip. After downloading, unpack the .zip file to a suitable location and follow the instructions given in the readme file.
To configure ScriptX Printing to use a particular account:
Also ensure that the required identity is given access permission in default DCOM security.
After configuration, it is suggested that the above tests are run again to ensure successful operation.
During initial configuration access checks to the COM+ application were disabled - you should review this configuration and modify to your requirements. If you do re-enable access checks, please note that ScriptX makes no use of any context information and therefore a Security Level of Perform access checks only at the process level is likely to be most appropriate.
If you do decide to enforce access checks, suitable roles must be created and the appropriate accounts added to those roles for the particular server system in use.
To successfully use ScriptX Printing with ASP.NET, the COM+ Application should be configured to run under a named account as described for ASP deployment, and the IIS application configured as medium or high protection (or an appropriate application pool used).
In addition, for IIS 5/5.1, the ASPNET account may need to be added to the list of accounts with default DCOM launch and access rights (if the account does not already have these rights).
The use of the component is essentially as described in the Printing section above, however a number of rules must also be followed when using the component within an aspx page:
<%@ Page aspcompat=true Language="VB" debug="true" %>
<script language = "vb" runat = "server">
Sub ScriptXPrint()
dim factory as Object
Dim printing as Object
dim i as Integer
Try
' Create the ScriptX object
factory = CreateObject("ScriptX.Factory")
' Get the printing object - this allows for more efficient access
' and also enables timely release of the objects
printing = factory.printing
' perform some printing
printing.header = "ScriptX Printing - Printing at the Server"
printing.footer = "Printed at the server"
printing.printHTML("http://localhost/default.htm") ' Change this URL to an appropriate page on your server.
Catch e as Exception
Response.Write("Print failed: " + e.Message)
End Try
if NOT factory is nothing then
' Closedown the ScriptX object - *required*
factory.ShutDown()
' Now ask .NET to release the objects. There should be only one reference
' on each object, but we loop until there are no references just in case.
i = System.Runtime.InteropServices.Marshal.ReleaseComObject(printing)
while i>0
i = System.Runtime.InteropServices.Marshal.ReleaseComObject(printing)
end while
i = System.Runtime.InteropServices.Marshal.ReleaseComObject(factory)
while i>0
i = System.Runtime.InteropServices.Marshal.ReleaseComObject(factory)
end while
end if
factory = nothing
End Sub
</script>
A sample in C# is provided in the samples download.