INFO: What sets the fax TSID and CSID?
	INFO: Firewall Setup for ADImport Server
	PRB: Error 119 on Lane Fax printers
	HOWTO: Import an XML User List into UserAdmin
	INFO: Passport Client Startup Parameters
	INFO: SMTP Message Importance
	INFO: DCOM Setup for Passport Clients
	INFO: Overview of Passport Client/Server Setup
	INFO: DCOM Setup for Passport Message Server
	BUG: CIAFax (content-implied addressing) does not work with Crystal Reports 10
	HOWTO: Change the Passport service account
	INFO: DCOM Setup and Assignments
	PRB: What does DIAL_NO_LOOP_CUR mean?
	PRB: Issues with client applications and administration of Passport-4000
	ENHANCEMENT: Passport4000 MessageTracker, Start and End Date Selection
	ENHANCEMENT: Passport4000 Audit, Total ‘Items’ count
	ENHANCEMENT: Passport4000 MessageTracker, Show the Creation Date/Time
	HOWTO: Revert to an earlier version of a Brooktrout PNP driver
	INFO: NO_LOOP_CURRENT failure during a call
	HOWTO: System Reference Number Customization
	INFO: Effect of applying a fax banner to existing pages
	INFO: Passport and WebSphere MQ)
	INFO: Using Lane OCR
	INFO: Document Conversion Installs
	INFO: Windows Firewall Setup for DCOM
	INFO: Manually augmenting department assignments
	INFO: Outlook-compatible enhanced SMTP addressing
	HOWTO: Delivery Report Customization
	HOWTO: How to embed message options in the Subject Line
	PRB: System Sends Faxes without Converting Attachments

INFO: What sets the fax TSID and CSID?

The ID that is sent by a fax sender is known as the TSID. The ID that is presented by a fax recipient is knows as the CSID.

For all current Passport fax drivers, the TSID content is always set from the id_string entry of the btcall.cfg configuration file.

The CSID content may come from several places depending on the type of driver and the configuration. For certain special configurations involving DTMF access, the CSID is created from the calling user's ID and that user's specific sequence number, but these configurations are not common.  Another uncommon setting that can be specified in the fax syscon is to answer with the assigned 'R' number, followed by a constant syscon-specified string. Otherwise, for the TR-114/Trufax drivers (for Brooktrout API 3.7-4.3), the CSID will also be set from the id_string entry of the btcall.cfg file, and will therefore be the same as the TSID.

For all TR1034 drivers, and for the fax service, except for the first two options described above, the CSID will by default be set from the Fax ID field, which is set as part of the Banner Info, in the fax syscon. However, it is possible that if the country_code setting in the btcall.cfg file is set to certain country settings, then the CSID will not be permitted to be overridden, and will be set only by the id_string setting. Note that the default country_code (USA) does permit the override. In any case, for all TR1034 drivers and services, the TSID is set from the id_string.

The banner info of the fax syscon, except as noted above, is used only in the formatting of the standard fax banner line.

INFO: Firewall Setup for ADImport Server

The server side of ADImport runs as a Windows service on the server machine. You may have to modify the firewall settings on the server machine to allow connections from the client applications.

For ADImport server, there are two exceptions to enter (assuming a Windows Firewall).

First allow port 704 to be accessed.

Then allow the service module ADImport.exe

The two exceptions will look as follows:

PRB: Error 119 on Lane Fax printers

Certain updates, patches, hotfixes, service packs, etc on Windows 2000 and Windows XP caused a compatibility problem with certain types of device drivers, including the Lane Fax drivers. These drivers include the DocConvert, Background, as well as all Fax Manager Lane Fax printers. The error will show up during installation, and/or during subsequent attempted usage, as either 'error 119' or 'The system does not support the command requested'.

On Windows 2000, this incompatibility was introduced after some unknown update. The resolution was provided in a later unknown update. It is not known exactly which updates caused and fixed the problem. The Microsoft update descriptions do not directly mention this type of problem. All that is really known is that if all updates are installed as of the time of this writing (27 May 2008), the problem should not exist.

On Windows XP, the introduction of the incompatibility has been associated with SP1, and the resolution was provided in SP2.

HOWTO: Import an XML User List into UserAdmin

The UserAdmin program has the ability to import a list of users contained in an XML file.  The XML file must contain a ‘PassportUsers’ element, which in turn contains a sequence of ‘PassportUser’ elements.  Each of these PassportUser elements then contains the following elements:

The elements indicated as ‘Multi’ may appear multiple times in the PassportUser element, thus permitting a single user to have more than one Fax DID address, Email address, etc.  These element names may also contain a suffix (e.g. DIDAddress2, DIDAddress3, etc) to accommodate certain XML environments that do not easily permit a single element to be repeated (such as Microsoft Excel).

Note that early versions of Passport 3000 UserAdmin accepted 'EmailOriginator' rather then 'EmailAddress'. Versions later than 2008.05.20 accept either element name. Passport 4000 UserAdmin accepts only 'EmailAddress'.

Very early pre-release versions (prior to 2007.07.23) permitted only the import of new users. Versions after the original release date of 2007.11.05 also permit the update of existing users. When updating an existing user, the Password is ignored. All other fields must be filled in, or else the corresponding user values will be set to empty strings, or '0' integers.

INFO: Passport Client Startup Parameters

These applications include Audit, Covedit, Message Approve, Message Routing, Message Tracker, Retrieve, Review, SendMsg, Status, and User Admin. These applications all have provisions for handling startup parameters that can specify the server, userid, and password to be used. These parameters are as follows:

The parameters may be provided in any order. Not all parameters are required. For example, you may specify only the server to use, and still enter the userid and password manually.

One method to specify these parameters is to create shortcuts for the desired applications. Create the shortcut, and then modify the properties of the shortcut by editing the Target field under the Shortcut tab of the properties. Append the desired parameters to the target, and if desired, rename the shortcut to indicate which server it points to. For example, to specify a server IP address and a user, you might append '/s 192.168.1.40 /u fbloggs'.

If you provide a password as a shortcut parameter, you should understand that it is stored in the shortcut as plain text, and can easily be discovered by any user of your computer.

INFO: SMTP Message Importance

Although several SMTP header fields have been defined that can be interpreted as an indication of message priority ('priority', 'precedence', 'importance', various MS-fields), the 'Importance' field seems to be the most common, and is also supported by Microsoft Outlook.

'Importance' can have a value of 'high', 'normal', or 'low'. However, it appears that as used by Outlook, the field is omitted if it is set to 'normal'.

The SMTP driver can be configured to recognize the 'Importance' field on incoming messages, as well as generate the field on outgoing messages. The configuration is performed by editing the driver's ini file, which is typically smtpsmtp.ini. The following table lists the values that may be added to the ini file. If the values are omitted, the default values will be used.

As a default, the SMTP driver will assign a priority of '1' to all incoming messages having normal or 'no' importance, '0' for low, and '2' for high. Also by default, the SMTP driver will not specify importance on outbound messages. If outbound importance is desired, set the SENDIMPORTANCE to '1'.

INFO: DCOM Setup for Passport Clients

First, run the program ‘Component Services’.  You can do this from ‘Control Panel’ – ‘Performance and Maintenance’ – ‘Administrative Tools’ – ‘Component Services’, or you can just ‘run’ ‘dcomcnfg’.

Open up the tree under Component Services to show Computers, and then My Computer.  Then right click on My Computer to show its properties.

Go to the ‘Default Properties’ tab, and make sure that the ‘Enable Distributed COM on this computer’ box is checked.

No additional DCOM or firewall settings should be required at the client computer end. For configuration of the Passport Message Server computer, please consult the related articles.

INFO: Overview of Passport Client/Server Setup

Several issues must be addressed in order to successfully use remote Passport client applications with a Passport Message Server. These are:

	DCOM Setup for Passport Message Server
	DCOM Setup for Passport Clients
	Windows Firewall setup for DCOM
	Domain membership/Guest account/duplicate logons
	CMON identity

The first three items are addressed in other related articles. This article addresses the last two items.

DOMAIN MEMBERSHIP / GUEST ACCOUNT / DUPLICATE LOGONS

Ideally, Passport clients and the Passport Message Server will have some type of Domain relationship. Either all will be a member of the same domain, or else their domains will have a trust relationship. This will permit the Passport Message Server to authenticate and identify the client user. If this Domain relationship does not exist, then the alternatives are either to enable the 'guest' account, use duplicate logon accounts, or to disable authentication.

Enabling the 'guest' account can permit access to the Passport Message Server from outside its domain. However, this will not permit an implicit identification of the client user, therefore 'Passport' security must be used to identify the client user, and clients will be required to login.

Another alternative is to create duplicate accounts at the Message Server (or its domain) that match exactly the user ID and password that is used at the off-domain client (or its domain). This will still implicitly identify the client user thus permitting 'NT' security to be used. Every off-domain client user must have a duplicate account created at the Message Server.

The final alternative is to disable totally the DCOM authentication mechanism. This is done by setting the Authentication Level to (none) at the Message Server. Although it is possible to set the default Authentication Level for the entire server computer to None, it is required only to set this for the CMON application. With no authentication, there is no implicit identification of the client user, therefore 'Passport' security must be used to identify the client user, and clients will be required to login.

CMON Identity

When the Passport Message Server is run as a service, as is the case on all Passport 4000's and most Passport 3000's, the CMON application must be configured with an identity that matches that of the Passport service logon. On a Passport 3000, this can be done under the Remote Access tab of CMON Configuration. Enter the account name and password, and click the Set Account button. Make certain to examine the subsequent message box replies to check for any problems.

Alternatively for Passport 3000's and for all Passport 4000's, the CMON Identity can be set using DCOMCNFG. Under Component Services - Computers - My Computer - DCOM Config, locate Passport Cmon Application (for the Passport 3000) or Passport 4000 Call Monitor (for the Passport 4000), and examine its properties. Under the Identity tab, set the account and password to match the account and password that is used for the Passport service.

INFO: DCOM Setup for Passport Message Server

First, run the program ‘Component Services’.  You can do this from ‘Control Panel’ – ‘Performance and Maintenance’ – ‘Administrative Tools’ – ‘Component Services’, or you can just ‘run’ ‘dcomcnfg’.

Open up the tree under Component Services to show Computers, and then My Computer.  Then right click on My Computer to show its properties.

Go to the ‘Default Properties’ tab, and make sure that the ‘Enable Distributed COM on this computer’ box is checked.

Next, go to the COM Security tab.

Note that this is a bit different than Windows 2000.  In the Access Permissions area, click the Edit Limits button.

If ‘Everyone’ is not listed, add it to the list, and insure that both Local Access and Remote Access boxes are checked in the ‘Allow’ column.  Click OK, and then in the Launch and Activation Permissions area, click the Edit Limits button. Again, if ‘Everyone’ is not listed, add it to the list, and insure that all local and remote, launch and activation, boxes are checked in the ‘Allow’ column.  Then click OK.

The settings above, in addition to enabling basic DCOM access to the computer, also permit the Passport CMON server to set its own launch and access permissions.

BUG: CIAFax (content-implied addressing) does not work with Crystal Reports 10

SYMPTOMS

Applications involving Crystal Reports versions 9 and 10 may no longer work where they may have previously worked using Crystal Reports 8.5.

The CIAFax (Content Implied Addressing) print driver attempts to extract addressing information from an internal processing stream that examines the raw characters being printed. This process looks for certain addressing keyword strings, such as 'Fax Number', and then extracts the following characters as the address. With Crystal Reports 9 and 10, the 'static', or fixed, sections of the report appear garbled in this raw character stream, while the variable sections of the report appear legible. This can be seen if the 'shadow' file option is enabled.

CAUSE

The cause of the problem is not totally understood, but is possibly related to a change within Crystal associated with Unicode character sets. Other Crystal users have complained of similar problems concerning printing to remote or network printers (in environments having nothing to do with fax, Lane, or ImageMaker).

WORKAROUND

The garbled address characters can be handled if the address search strings are changed to match the garbled characters. Since the garbled characters include some non-printable characters, it will be necessary to use some type of hex editor to modify the search strings. The search strings are contained in a file named CIAFAX.CTL. Use the following substitution chart to replace the search characters with their garbled counterpart.

For example, if the original search string was "Fax:", then replace it with the hex characters 0x29, 0x44, 0x5b, 0x1d.

STATUS

This problem is under investigation by ImageMaker.

HOWTO: Change the Passport service account

Create or choose the new account to use for the Passport service. If the Passport machine belongs to a domain, this must be a domain account.

The account must be given Logon as a service rights. If the account is a local account, this can be set on the local computer. If it is a domain account, it must be set at the domain controller.

Use the Services applet on the local computer to change the logon for the Passport service to the chosen account.

Go to the installation folder for the Passport (typically c:\Program Files\Passport4000) and there run the RegisterDcom application. Enter the same new account ID and password. This step will change the DCOM identity for cmon.exe, cmonadmin.dll, passportadmin.dll, pccmail.exe, and routinginfo.dll, thus permitting access from the MMC and Passport client applications.

Restart the Passport service.

INFO: DCOM Setup and Assignments

There are four parts of DCOM that can cause for a long day. One of these is the Widows Firewall and that discussion is contained in a related article (see below).

A second part involves registration.  Registration has two parts, COM registration and DCOM registration. DCOM registration is an extension of COM registration and all Lane modules should have been modified to do both registrations using regsvr32 on DLLs or running the EXE with a parameter of -regserver. DCOM registration can be verified by using the system module dcomcnfg (started from a command prompt).

If you do not see the application of interest in the DCOM Config list, please contact Lane Engineering.

The next two items are the most likely to cause problems. They have to do with security.

Identity

In most cases, you will need to be running as “This User”. This is the user ID that the DCOM module uses when it runs. That user ID determines the privileges that are given to the DCOM module. The necessary privileges vary by DCOM module. For example, if the module needs to access network drives, then the user ID must have that privilege. If the module needs to access local drives, then it must have that privilege.

As a specific example, the DocConvert operation running in DCOM mode needs Administrative privileges on the local machine. It does not need network Administrative privileges. The assignment of local administrative privileges can be accomplished in two ways. One is to create a local user and place that user in the Administrator group. Another is to take a Domain User and assign that user to the local Administrator group.

Once a DCOM module is setup to run, then it must be determined who can access the features of the module. This is done on the Security tab:

In most case the “Use Default” will be inadequate.  In the Customize dialog, add the network Everyone to the name list and allow Everyone all privileges. The setup for Launch and Activation is shown below.

Do the same thing for Access Permission.

If the use of Everyone is a problem, you can add network individuals or a network group which includes all individuals needing access to the DCOM module.

PRB: What does DIAL_NO_LOOP_CUR mean?

SYMPTOMS

When attempting to dial a call, the fax driver or fax service will report a CUI/Reason code of DIAL_NO_LOOP_CUR.

CAUSE

Analog TR1034 boards have the ability to detect loop current.  This error code probably indicates that there is no line plugged in to the board, or that the line is totally dead.   This is subtly different than DIAL_NO_DIAL_TONE, which would suggest that there is a line, with line current, but that no dial tone can be detected when going 'off-hook'. There is a slight problem of interpretation since the DIAL_NO_DIAL_TONE is mapped, by default, to the 'non-busy' (NB) category rather than the 'exchange' (XG) category, thus the retries may not be performed in the expected manner.

WORKAROUND

In the Passport 3000, the FaxRetry program should be used to map the DIAL_NO_LOOP_CUR error to the BADLINE error type.

STATUS

This problem will be studied further to determine if the default handling should be altered.

PRB: Issues with client applications and administration of Passport-4000

Stimulate discussion regarding tools used to administer the Passport-4000 which will NOT be MMC snap-ins.

- PpClient Audit returns result fast, but does not have total items count
- PCC Audit* is incredibly slow, but does have a total items count
- MessageTracker is almost as good as Audit but does not show received items

*PCC for the most part is slow, especially Audit and Archive, have been advised that there is a fix for this. It is also a possibility that PCC is not suitable for system administration which would mean the continued use of PPCLIENT applications.

ENHANCEMENT: Passport4000 MessageTracker, Start and End Date Selection

Date selection, can set start and end independent can cause erroneous data to be returned, i.e. End date can be prior to Start Date.

ENHANCEMENT: Passport4000 Audit, Total ‘Items’ count

Request that total ‘Items’ count, for currently displayed records, be added to status bar.

ENHANCEMENT: Passport4000 MessageTracker, Show the Creation Date/Time

Allowing an option to show the Creation Date/Time of a message would be useful.

HOWTO: Revert to an earlier version of a Brooktrout PNP driver

The following procedure has been found to work in Windows XP Professional.  It may work in other Windows versions also, but it has not been tested in any other versions.

1) Stop all applications that are using the Brooktrout board.  This includes Passport itself, and any Brooktrout-supplied diagnostics.

2) Open the Device Manager.  One way to do this is to right-click on My Computer, select Manage, and there open the Device Manager.  Another way is to right-click on My Computer, select Properties, select the Hardware tab, and there open the Device Manager.

3) Locate the Brooktrout board in the device list.  It may be under the heading ‘Computer Telephony’, or ‘Brooktrout Hardware’, or possibly something else.  Expand that heading to show the particular board, right-click it, and select Properties.  Select the Driver tab, and make note of the Driver Version.  Note that the Driver Version corresponds to the Brooktrout API level, and NOT to the Brooktrout SDK level.  The API/Driver Versions that have been used or may be used in the near future include 4.6.x.x, 4.7.x.x, 4.8.x.x, 4.9.x.x, 5.2.x.x, and 5.3.x.x.

4) If you are still viewing the Driver tab of the Board Properties, click the ‘Update Driver…’ button.  Or if you are viewing the Device Manager, right-click the Brooktrout board, and select Update Driver.

5) You should see a Hardware Update Wizard, whose first page will ask you to connect to Windows Update.  You should answer ‘No, not this time’.

6) Next you will see a choice to ‘Install the software automatically’, or ‘Install from a list or specific location’.  You must pick the second choice.

7) Next you will see a choice to ‘Search for the best driver…’ or ‘Don’t search…..’  If you were updating to a later version, you might be able to use the first choice.  But when reverting to an older version, you must pick the second (‘Don’t search’) choice.

8) On the next screen (‘Select the device driver…’), click the ‘Have Disk…’ button.  Do not pay any attention to the list of compatible hardware.

9) On the resulting ‘Install From Disk’ screen, use the Browse button to find the folder that contains the ‘inf’ file for the desired driver version level.  Click the OK button on this ‘Install From Disk’ screen, and you should return back to the ‘Select the device driver’ screen.  Now you may click the ‘Next’ button. 

10) You should now see the wizard proceed to install the driver.  You will likely be warned that you are attempting to overwrite newer files with older files.  You should answer ‘Yes’ to each of the ‘Overwrite the newer file’ questions.

11) Click ‘Finish’ to complete the wizard.  You will be told that you must restart the computer.  You may want to answer ‘No’ so that you can perform a quick check to see if the reversion worked.

12) The Device Manager should still be open, and should show your Brooktrout board, but possibly with a different name or under a different heading than before.  Right-click the board, and select Properties (as in step 3).  Select the Driver tab, and verify that the Driver Version is the one you wanted.  If not, then this procedure failed, or you did not pick the ‘Don’t search’ choice in step 7.

13) If the procedure worked, you will need to restart the computer.

INFO: NO_LOOP_CURRENT failure during a call

NO_LOOP_CURRENT can occur during a call if it gets disconnected.

HOWTO: System Reference Number Customization

Passport messages generally have an ‘R’ number (file name) and a Reference number associated with them.  This reference number is normally assigned to the message by the driver on which the message is received.  In some cases, the reference number is provided by the content of the message, and in some other cases it is merely the same as the ‘R’ number itself.

There is an option by which the Passport system can assign a customizable, system-wide, System Reference Number to incoming messages.  This System Reference Number consists of a date portion, which represents the current date, and a sequence number, which is reset daily.  This option is configured by making or altering entries in the cmon.ini file, which is located in the (LMS)\INI folder.

To enable this option, add or change the following line in the cmon.ini file:

USESYSTEMREFERENCE=1

This system reference number will be applied to any received message which does not already have a reference number assigned to it.  To be effective, you may need to configure the receiving drivers NOT to assign a reference number.  Also note that some drivers may internally incorporate the System Reference Number option, and perform this function within the driver.

The default format of the reference number consists of two-digit month, a two-digit date, and a five-digit sequence number.  For example a reference number during July 23 might appear as:

072300139

You may change the number of digits in the sequence number portion by adding or changing the following line in the cmon.ini file:

SYSTEMREFERENCESEQDIGITS=7

Digit values larger than 9 or less than 3 will be limited to 9 and 3 respectively.  Be warned that a too-small digit count can cause the reference number to be ‘recycled’ in the course of a single day, which can make message tracking difficult.  And be warned that a too-large digit count can cause problems for some Passport applications.  Some older programs expected the reference number to be nine characters or less.

You may change the formatting of the date portion of the reference number by adding or changing the following line in the cmon.ini file:

SYSTEMREFERENCEDATEFORMAT=%m%d

This format consists of a mixture of constant characters and formatting characters.  Formatting characters are preceded by a ‘%’.  Any other characters are treated as constant characters.  Below is a table of formatting characters:

%a           Abbreviated weekday name

%A           Full weekday name

%b           Abbreviated month name

%B          Full month name

%c           Date and time representation appropriate for locale

%d           Day of month as decimal number (01 – 31)

%H          Hour in 24-hour format (00 – 23)

%I             Hour in 12-hour format (01 – 12)

%j             Day of year as decimal number (001 – 366)

%m          Month as decimal number (01 – 12)

%M          Minute as decimal number (00 – 59)

%p           Current locale’s A.M./P.M. indicator for 12-hour clock

%S           Second as decimal number (00 – 59)

%U          Week of year as decimal number, with Sunday as first day of week (00 – 53)

%w          Weekday as decimal number (0 – 6; Sunday is 0)

%W         Week of year as decimal number, with Monday as first day of week (00 – 53)

%x           Date representation for current locale

%X           Time representation for current locale

%y           Year without century, as decimal number (00 – 99)

%Y           Year with century, as decimal number

%z, %Z Time-zone name or abbreviation; no characters if time zone is unknown

For example, a date format of SYS&Y&j would produce the constant characters “SYS”, followed by a four-digit year, followed by a three-digit Julian date.  When combined with a sequence number, this might appear as:

SYS200419200285

As with the warning on the sequence digit count above, be aware of formatting problems that can be caused when using a long date format with some older applications.

INFO: Effect of applying a fax banner to existing pages

The ‘fax banner’ is a line of data that is applied to the top of each transmitted fax page at the time of transmission.  When the data being transmitted is already in the form of pages, such as an existing fax, or a Word, Excel, or PDF document that has been converted to tiff pages, then there is a dilemma in how the fax banner should be applied to these pages.  The two most obvious choices are to extend the length of the page to accommodate the fax banner, or to replace the existing upper portion of the page with the fax banner.

If the page is extended, then all the original data on the page may be retained.  However, the length of the page will of course increase by at least the height of the banner (~ 2-3 mm).  This may not cause a problem under normal circumstances.  However, consider the scenario where documents are received as fax, and then re-sent as fax, and again re-sent as fax, etc.  If each retransmission were to extend the length, then the growth will become noticeable.  It has been observed that some plain-paper fax machines will take any page that exceeds the plain paper size by more than a few mm and print that page as two pages.

To avoid extending the page, the other simple option is to replace the existing uppermost 2-3 mm of the page with the new fax banner data.  This is what most ‘normal’ fax machines do.  This avoids the elongation of the page with each transmission, but of course has the effect of obliterating the underlying previously-existing data.

The Call2tifr.dll is responsible for formatting fax pages immediately prior to transmission for all fax drivers in use since 2000.  As part of that formatting, it also creates the banner lines, except for those types of banner lines produced by the ‘Customized Banner’ style (refer to the article on Fax Banner Customization).  Prior to version 2005.03.18, it created banner lines by extending the length of the page.  In response to complaints of double-pages produced by plain-paper fax recipients, the program was changed in 2005.03.18 so that it created the standard banner lines by replacing the existing upper portion of the page.

The change to partially replace, rather than elongate, the page has sparked a new set of complaints.  Some users have designed cover sheets that contain graphic images and/or text that are positioned at the extreme top edge of the page.  The effect of the banner ‘replacement’ mode is to replace the upper parts of those graphics.

Therefore, beginning with version 2006.07.05, the Call2tifr.dll was modified to check for a declaration in the lms.ini file as follows:

BANNEREXTENDSPAGE=1

If this declaration exists, then the banner generation will extend the length of the fax page (by the length of the banner) as it did in versions prior to 2005.03.18.  If this declaration does not exist, or is set to anything other than ‘1’, then the banner will replace the existing upper portion of the page.  This declaration must be entered in the lms.ini file on all commservers and on the message server, and will take effect within one minute (i.e. no restart is required).

INFO: Passport and WebSphere MQ)

Introduction to message queuing

The MQSeries products enable programs to communicate with one another across a network of unlike components – processors, operating systems, subsystems and communication protocols – using a consistent application programming interface.

Applications designed and written using this interface are known as message

queuing applications, as they use the messaging and queuing style:

Messaging

Programs communicate by sending each other data in messages rather than calling each other directly.

Queuing

Messages are placed on queues in storage, allowing programs to run independently of each other, at different speeds and times, in different locations, and without having a logical connection between them.

This chapter introduces messaging and queuing concepts, under these headings:

What is message queuing?

Message queuing has been used in data processing for many years. It is most commonly used today in electronic mail. Without queuing, sending an electronic message over long distances requires every node on the route to be available for forwarding messages, and the addressees to be logged on and conscious of the fact that you are trying to send them a message. In a queuing system, messages are stored at intermediate nodes until the system is ready to forward them. At their final destination they are stored in an electronic mailbox until the addressee is ready to read them.

Even so, many complex business transactions are processed today without queuing. In a large network, the system might be maintaining many thousands of connections in a ready-to-use state. If one part of the system suffers a problem, many parts of the system become unusable. 

You can think of message queuing as being electronic mail for programs. In a message queuing environment, each program from the set that makes up an application suite is designed to perform a well-defined, self-contained function in response to a specific request. To communicate with another program, a program must put a message on a predefined queue. The other program retrieves the message from the queue, and processes the requests and information contained in the message. So message queuing is a style of program-to-program communication.

Queuing is the mechanism by which messages are held until an application is ready to process them. Queuing allows you to:

	Communicate between programs (which may each be running in different environments) without having to write the communication code.
	Select the order in which a program processes messages.
	Balance loads on a system by arranging for more than one program to service a queue when the number of messages exceeds a threshold.
	Increase the availability of your applications by arranging for an alternative system to service the queues if your primary system is unavailable.

What is a message?

In message queuing, a message is simply a collection of data sent by one program and intended for another program. MQSeries defines four types of message:

	Datagram A simple message for which no reply is expected
	Request A message for which a reply is expected
	Reply A reply to a request message
	Report a message that describes an event such as the occurrence of an error

Message descriptor

An MQSeries message consists of control information and application data. The control information is defined in a message descriptor structure (MQMD) and contains such things as:

	The type of the message
	An identifier for the message
	The priority for delivery of the message
	The participating programs, not MQSeries, determine the structure and content of the application data.

(Please read the last bullet item again.  It is important that you understand the implications.)

Message channel agent

A message channel agent moves messages from one queue manager to another.

What is a message queue?

A message queue, known simply as a queue, is a named destination to which messages can be sent. Messages accumulate on queues until they are retrieved by programs that service those queues.

Queues reside in, and are managed by, a queue manager (see “What is a queue manager?”). The physical nature of a queue depends on the operating system on which the queue manager is running. A queue can either be a volatile buffer area in the memory of a computer, or a data set on a permanent storage device (such as a disk). The physical management of queues is the responsibility of the queue manager and is not made apparent to the participating application programs.

Programs access queues only through the external services of the queue manager. They can open a queue, put messages on it, get messages from it, and close the queue. They can also set, and inquire about, the attributes of queues.

What is a queue manager?

A queue manager is a system program that provides queuing services to applications. It provides an application-programming interface so that programs can put messages on, and get messages from, queues. A queue manager provides additional functions so that administrators can create new queues, alter the properties of existing queues, and control the operation of the queue manager.

For MQSeries message queuing services to be available on a system, there must be a queue manager running:

	On OS/400, OS/390, OS/2, Windows NT, Digital OpenVMS, and UNIX systems, you can have more than one queue manager running on a single system (for example, to separate a test system from a “live” system). To an application, each queue manager is identified by a connection handle (Hconn).
	On the VSE/ESA and Windows platforms, you can have only one queue manager running on a single system. Hconn is still used, but only to give compatibility with other MQSeries platforms.

Many different applications can make use of the queue manager’s services at the same time and these applications can be entirely unrelated. For a program to use the services of a queue manager, it must establish a connection to that queue manager.

For applications to be able to send messages to applications that are connected to other queue managers, the queue managers must be able to communicate among themselves. MQSeries implements a store-and-forward protocol to ensure the safe delivery of messages between such applications.

What is a cluster?

A cluster is a network of queue managers that are logically associated in some way.

Clustering is available to queue managers on the following platforms:

	MQSeries for AIX, V5.1
	MQSeries for AS/400, V5.1
	MQSeries for HP-UX, V5.1
	MQSeries for OS/2 Warp, V5.1
	MQSeries for OS/390, V2.1
	MQSeries for Sun Solaris, V5.1
	MQSeries for Compaq Tru64 UNIX, V5.1
	MQSeries for Windows NT, V5.1

In a traditional MQSeries network using distributed queuing, every queue manager is independent. If one queue manager needs to send messages to another it must have defined a transmission queue, a channel to the remote queue manager, and a remote queue definition for every queue to which it wants to send messages.  If you group queue managers in a cluster, the queue managers can make the queues that they host available to every other queue manager in the cluster. Then, assuming you have the necessary network infrastructure in place, any queue manager can send a message to any other queue manager in the same cluster without the need for explicit channel definitions, remote queue definitions, or transmission queues.

There are two quite different reasons for using clusters: to reduce system administration and to improve availability and workload balancing.

As soon as you establish even the smallest cluster you will benefit from simplified system administration. Queue managers that are part of a cluster need fewer definitions and so the risk of making an error in your definitions is reduced.

For details of all aspects of clustering, see the MQSeries Queue Manager Clusters book, SC34-5349.

What is a shared queue, a queue-sharing group, and intra-group queuing?

Shared queues, queue-sharing groups, and intra-group queuing are only available on MQSeries for OS/390, V2.2 with sysplex.

 A shared queue is a type of local queue whose messages can be accessed by one or more queue managers that are in a sysplex. (This is not the same as a queue being .shared. by more than one application, via the same queue manager.)

The queue managers that can access the same set of shared queues form a group called a queue-sharing group (QSG). They communicate with each other by means of a coupling facility (CF) that stores the shared queues. See the MQSeries for OS/390 Concepts and Planning Guide for a full discussion of queue-sharing groups.

Message transfer between queue managers in a queue-sharing group is called intra-group queuing (IGQ), and lets you perform fast message transfer without defining channels.

What is an MQSeries client?

An MQSeries client is an independently installable component of an MQSeries product. It allows you to run MQSeries applications, by means of a communications protocol, to interact with one or more Message Queue Interface

(MQI) servers on other platforms and to connect to their queue managers.

For full details on how to install the MQSeries client component and use the environment, see the MQSeries Clients book.

Main features of message queuing

The main features of applications that use message queuing techniques are:

	There are no direct connections between programs.
	Communication between programs can be time-independent.
	Work can be carried out by small, self-contained programs.
	Communication can be driven by events.
	Applications can assign a priority to a message.
	Security.
	Data integrity.
	Recovery support.

 No direct connections between programs

Message queuing is a technique for indirect program-to-program communication. It can be used within any application where programs communicate with each other. Communication occurs by one program putting messages on a queue (owned by a queue manager) and another program getting the messages from the queue.

Programs can get messages that were put on a queue by other programs.

The other programs can be connected to the same queue manager as the receiving program, or to another queue manager. This other queue manager might be on another system, a different computer system, or even within a different business or enterprise.

There are no physical connections between programs that communicate using message queues. A program sends messages to a queue owned by a queue manager, and another program retrieves messages from the queue.

As with electronic mail, the individual messages that may be part of a transaction, travel through a network on a store-and-forward basis. If a link between nodes fails, the message is kept until the link is restored, or the operator or program redirects the message.

 The mechanism by which a message moves from queue to queue is hidden from the programs. Therefore the programs are simpler.

Time-independent communication

Programs requesting others to do work do not have to wait for the reply to a request. They can do other work, and process the reply either when it arrives or at a later time. When writing a messaging application, you need not know (or be concerned) when a program sends a message, or when the target is able to receive the message. The message is not lost; it is retained by the queue manager until the target is ready to process it. The message stays on the queue until it is removed by a program.

Small programs

Message queuing allows you to exploit the advantages of using small, self-contained programs. Instead of a single, large program performing all the parts of a job sequentially, you can spread the job over several smaller, independent programs. The requesting program sends messages to each of the separate programs, asking them to perform their function; when each program is complete, the results are sent back as one or more messages.

Event-driven processing

Programs can be controlled according to the state of queues. For example, you can arrange for a program to start as soon as a message arrives on a queue, or you can specify that the program does not start until there are, for example, 10 messages above a certain priority on the queue, or 10 messages of any priority on the queue.

Message priority

A program can assign a priority to a message when it puts the message on a queue. This determines the position in the queue at which the new message is added. Programs can get messages from a queue either in the order in which the messages appear in the queue, or by getting a specific message. (A program may want to get a specific message if it is looking for the reply to a request it sent earlier.)

Security

Authorization checks are carried out on each resource, using the tables that are set up and maintained by the MQSeries administrator.

	RACF or other external security managers may be used within MQSeries for OS/390.
	There is no authorization checking within MQSeries for OS/2 Warp; however, an interface is provided to enable you to build and install your own.
	Within MQSeries on UNIX systems, AS/400, Compaq (DIGITAL) OpenVMS, Tandem NonStop Kernel, and Windows NT, a security manager, the Object Authority Manager (OAM), is provided as an installable service. By default, the OAM is active.
	On VSE/ESA, security is provided by CICS.

Data integrity

Data integrity is provided via units of work. The synchronization of the start and end of units of work is fully supported as an option on each MQGET/MQPUT, allowing the results of the unit of work to be committed or rolled back. Syncpoint support operates either internally or externally to MQSeries depending on the form of syncpoint coordination selected for the application.

Recovery support

For recovery to be possible, all persistent MQSeries updates are logged. Hence, in the event that recovery is necessary, all persistent messages will be restored, all in-flight transactions will be rolled back and any syncpoint commit and backouts will be handled in the normal way of the syncpoint manager in control.

MQSeries clients and servers

A server application will not have to be changed to be able to support additional MQSeries clients on new platforms. Similarly, the MQSeries client will, without change, be able to function with additional types of server. See the MQSeries Clients book for more information.

Benefits of message queuing to the application designer and developer

Some of the benefits of message queuing are:

	You can design applications using small programs that you can share between many applications.
	You can quickly build new applications by reusing these building blocks.
	Applications written to use message queuing techniques are not affected by changes in the way queue managers work.
	You do not need to use any communication protocols. The queue manager deals with all aspects of communication for you.
	Programs that receive messages need not be running at the time messages are sent to them. The messages are retained on queues.
	Designers can reduce the cost of their applications because development is faster, fewer developers are needed, and demands on programming skill are lower than those for applications that do not use message queuing.

What can you do with MQSeries products?

MQSeries products are queue managers and application enablers. They support the IBM Message Queue Interface (MQI) through which programs can put messages on a queue and get messages from a queue.

MQSeries for non-OS/390 platforms

With MQSeries for non-OS/390 platforms you can write applications that:

	Send messages to other applications running under the same operating systems. The applications can be on either the same or another system.
	Send messages to applications that run on other MQSeries platforms.
	Use message queuing from within CICS Transaction Server for OS/2, CICS for AS/400, TXSeries for AIX, TXSeries for HP-UX, CICS for Siemens Nixdorf SINIX, TXSeries for Sun Solaris, and TXSeries for Windows NT, DOS, and Windows 3.1 applications.
	Use message queuing from within Encina for AIX, HP-UX, SINIX, Sun Solaris, and Windows NT.
	Use message queuing from within Tuxedo for AIX, AT&T, HP-UX, SINIX and DC/OSx, Sun Solaris, Compaq Tru64 UNIX, and Windows NT.
	MQSeries can act as a transaction manager, and will coordinate updates made by external resource managers within MQSeries units of work. These external resource managers must comply to the X/OPEN XA interface.
	Process several messages together as a single unit of work that can be committed or backed out.
	Run from a full MQSeries environment, or run from an MQSeries client environment on the following platforms: – AS/400 – Digital OpenVMS – DOS – OS/2 – UNIX systems – VM/ESA® – Windows NT – Windows 3.1 – Windows 95 and Windows 98

Conclusion

There are three main points to remember when working with MQSeries. 

1. It is typically purchased, installed, and maintain by network personnel.  At this point it is not supplied as part of a Passport package.
2. The structure of the messages being passed between queues is defined by the applications not by MQSeries.  There is nothing in the queue that tells the application the structure of the message; the application must know prior to accessing the queue.  Thus, each customer may need a different Passport application.  This will have to be determined during the specification cycle.  The only application that currently exists is a driver for a New York customer that expects all messages to be plain text.
3. There is no standard Passport software for MQSeries.  Each customer will be different and require a different application(s).

INFO: Using Lane OCR

There are now six versions, 10, 11, 12, 12.5, 12.6 and 12.7 available for download as LaneOCRv10, LaneOCRv11, LaneOCRv12, LaneOCRv125, LaneOCRv126, and LaneOCRv127.

Versions 10, 11, and 12 are no longer supported by Scansoft. So if you find any problems, your only recourse is to upgrade to version 12.7.  We have found a serious problem in version 11 that will crash the application. Unfortunately the crash is so bad that it is not detectable by the application and cannot be dealt with in an orderly manner.  The crash will occur when the TIF document contains Arabic script, and probably other scripts as well, or random marks somewhere on the page.

The licenses are not interchangeable between versions.  The license must be specific for the version you are using.  To upgrade a version 11 license to version 12 costs about 200 USD.  The version 12 license will work with 12.5, 12.6 and 12.7.  You can contact Mark Gaeta at Scansoft (+19789772445) to acquire a new license.

You should not leave multiple versions of the OCR software on your machine. Remove the old version before installing the new.

Applications that are OCR aware require a DLL, RECIPRO.DLL, or they will not load and execute.  The bad news is that RECIPRO.DLL is different for each OCR version. The installs ship with a version of RECIPRO.DLL (currently version 12.7) but it may not be the one you need. The correct RECIPRO.DLL that you need is located in the directory where you installed the OCR modules.  Just replace the one that is co-located with the application with the one from the OCR directory.

The version information for RECIPRO.DLL is as follows:

INFO: Document Conversion Installs

The standard Document Conversion install has for some time been DocumentConversion.msi. The install process created a printer named Lane Fax DocCnvrt and the name of the primary module was DocCnvrt.exe. The install allowed a selection of DCOM mode, run as a service mode, or run from the startup folder mode. The latter two would monitor a Passport disk directory for documents to convert. The DCOM mode was initiated directly from CMON. The interface to the Lane Fax DocCnvrt printer required that a disk directory be monitored for certain files to determine when the print process was complete.

The interface to the printer was not very efficient and problems could occur if multiple Lane Fax printers were installed. In addition, the disk directory was usually one off the c: root and in current Windows Server versions access to those disk directories is limited unless administrative rights are given.

To address the problems, a new install DocumentConversionV2.msi was created. The install creates a printer named Lane Fax DocConvert and the primary module is DocConvert.exe. Please note the subtle change in the names. In addition, the interface to the printer was changed to use a communication technique called named pipes. This mode does not require monitoring of a disk directory. The DocConvert.exe is suspended until the printer module responds with the converted file.  This eliminates constant disk activity and the problems associated with multiple Lane Fax printers. The working disk directory was also moved to the TEMP directory of the user under which the module is running. This requires no special rights. The diagnostic log is also created in this TEMP directory. The TEMP directory is located at c:\Documents and Settings\username\Local Settings\Temp.

As before, the install allows a selection of DCOM mode, run as a service mode, or run from the startup folder mode.

A special version of the install named DocumentConversionV2-DCOM.msi also exists. This installs DocConvert.exe in DCOM mode which is the preferred mode of operation.

Before installing the V2 version, the older one needs to be removed.

The older install should no longer be used. However, it will be left in the download area for awhile.

INFO: Windows Firewall Setup for DCOM

JUST IN CASE, CHECK IF DCOM ENABLED

Run the Windows application dcomcnfg.exe. Expand the tree until you see the name of the computer.

Right click on My Computer, select Properties, and select the Default Properties tab.

SETUP WINDOWS FIREWALL

Run the Windows Firewall module an select the Exceptions tab.

Add a port as shown in the following that permits access through port 135 (the DCOM port).

Then add a program entry for each module that will be supporting DCOM. In the following example the Passport module CMON is added.

Some DCOM modules come in DLL form. For these to work, you need to add a program entry for DLLHOST.exe which is found in the \Windows\system32 directory.

INFO: Manually augmenting department assignments

The department information is maintained in the LMS\INI\DEPTS.INI file.  Note that if no user has ever been assigned to any department, this file might not exist.  The file consists of one or more text lines, with each line describing the departmental properties of a single user.  Each line contains 2 or 3 fields, separated by a tab character.  The fields are user id, department, and an admin flag (0 for user, 1 for admin).

You can use notepad to examine and edit this file, but you must be very careful not to disturb the ‘tab’ characters in the file, since they may not be obvious in their existence.  You must also make certain that no other users attempt to use the UserAdmin functions while you are manually editing the depts.ini file.

For illustrative purposes, assume that there are two departments named Sales, and Service.  In the Sales department, there are members ABrown, CDillon, and EFramish with CDillon as the administrator.  In the Service department, there are members GHall, IJones, and KLawrence with KLawrence as the administrator.  The depts.ini file would then appear thus:

 When you use notepad, the columns might not appear to line up as nicely as above, depending on the lengths of the individual entries.  Also observe that thus far, the order of these entries is not important.  Next we will examine two scenarios.  In the first, we will augment the table so that CDillon can monitor the messages not only of the Sales department, but also of the individual user IJones.  In the second scenario, we will augment the table so that KLawrence can monitor the messages of both the Sales and Service departments.

ALLOW A USER TO BE MONITORED BY ADDITIONAL DEPARTMENT ADMINISTRATORS

In this illustration, let’s assume that we want IJones’ messages to be monitored not only by her department administrator (KLawrence), but also by CDillon, the Sales department administrator.  To do this, you would add the following line to the end of the file: