Configuring a print queue

To use the message printing service, you must configure print queues. More than one print queue might be defined per OU. To define a print queue, you must configure a CO of type DnqPrintQueue and add it to the OU. The name of the CO corresponds to the name of the print queue.

To help you do this, FTM SWIFT generates, during customization, for each business OU, a script with a name of the form: 
deployment_dir/instance/admin/ou_dnqcpcqo.cli
where:
deployment_dir
Directory specified in the CDP initialization file.
instance
Name of the instance.
ou
Name of the OU.
The script contains the following commands:
add -ct DnqPrintQueue -ou DNIvOU -co <printQueueName> -attr InputEnabled
add -ct DnqPrintQueue -ou DNIvOU -co <printQueueName> -attr PrintDeviceType -val <DeviceType>
add -ct DnqPrintQueue -ou DNIvOU -co <printQueueName> -attr PrintDevice -val <Device>
add -ct DnqPrintQueue -ou DNIvOU -co <printQueueName> -attr PrintOptions -val <Options>
add -ct DnqPrintQueue -ou DNIvOU -co <printQueueName> -attr PrintLineLength -val <LineLength>
add -ct DnqPrintQueue -ou DNIvOU -co <printQueueName> -attr PrintPageLength -val <PageLength>
add -ct DnqPrintQueue -ou DNIvOU -co <printQueueName> -attr PrintFormatHeader -val <FormatHeader>
add -ct DnqPrintQueue -ou DNIvOU -co <printQueueName> -attr PrintFormatMessage -val <FormatMessage>
add -ct DnqPrintQueue -ou DNIvOU -co <printQueueName> -attr OrderSize -val <OrderSize>
add -ct DnqPrintQueue -ou DNIvOU -co <printQueueName> -attr OrderTimeout -val <OrderTimeout>
;add -ct DnqPrintQueue -ou DNIvOU -co <printQueueName> -attr Confirmation
;add -ct DnqPrintQueue -ou DNIvOU -co <printQueueName> -attr BICExpansion
add -ct DnqPrintQueue -ou DNIvOU -co <printQueueName> -attr Priority -val <Priority>
add -ct DnqPrintQueue -ou DNIvOU -co <printQueueName> -attr TargetQueue -val <TargetQueue>
add -ct DnqPrintQueue -ou DNIvOU -co <printQueueName> -attr TargetQMgr -val <TargetQueueManager>

add -ct DnqPrintOpAccessControl  -ou DNIvOU -co <printQueueName>  -attr status 
add -ct DnqPrintOpAccessControl  -ou DNIvOU -co <printQueueName>  -attr start
add -ct DnqPrintOpAccessControl  -ou DNIvOU -co <printQueueName>  -attr stop
add -ct DnqPrintOpAccessControl  -ou DNIvOU -co <printQueueName>  -attr reprint
add -ct DnqPrintOpAccessControl  -ou DNIvOU -co <printQueueName>  -attr confirm
add -ct DnqPrintOpAccessControl  -ou DNIvOU -co <printQueueName>  -attr release
add -ct DnqPrintOpAccessControl  -ou DNIvOU -co <printQueueName>  -attr delete

com -ou DNIvOU
The customization process substitutes the placeholder DNIvOU in the scripts with the name of the OU. Modify and run these scripts as follows:
  1. Copy the scripts into the home directory.
  2. Ensure that all commands that are to be executed are activated, that is, that they are not preceded by a semicolon character (;).
  3. Replace the following items in the copy of the scripts as required:
    <printQueueName>
    The name of the print queue. This name can be at most 30 characters long and can contain only:
    • Characters of the set [A-Za-z0-9]
    • Periods (.)
    • Hyphens (-)
    • Underscore characters (_)
    Note: If you use underscore characters in a print queue name, you must precede each of them with two backslash characters when administrating and operating this queue by using the CLI. For example, if you configure a print queue with the name My_Print_Queue, and if you want to start this queue later on, you must issue the following command to the print command service (DNQ_P_CMD):
    start -qname My\\_Print\\_Queue
    See Special characters for more information.
    InputEnabled
    This pseudo attribute indicates that the DnqPrintInputAdapter node of a message flow is to accept and import messages for this print queue and store them into the message database of the message printing service. If not configured, the DnqPrintInputAdapter node does not import messages for the queue.
    PrintDeviceType <DeviceType>
    Specifies the type of the printer device:
    Value Description
    0 This value corresponds to the device type PrintToPrinter. Specify this if you want print output to be sent to a printer.
    1 This value corresponds to the device type PrintToFile. Specify this if you want print output to be stored in files.
    PrintDevice <Device>
    The meaning of this attribute depends on the printer device type:
    • If PrintDeviceType=0 (PrintToPrinter), use this attribute if you need to specify parameters for the TSO ALLOCATE command. (Normally, there is no need to do this.) If you do not need to specify additional parameters, do not specify this attribute. For a list of possible parameters, refer to the description of the ALLOCATE command in z/OS® TSO/E Command Reference.
      Note: Do not specify the parameters FILE, LRECL, OUTDES, or SPIN, because these parameters are set by the message printing service and cannot be overridden.
    • If PrintDeviceType=1 (PrintToFile), this attribute specifies the directory in which the print output files are to be stored. This output directory must satisfy the following conditions:
      • It must be different from the working directory, which is specified by the WorkingDirectory attribute of the CO DnqPrintService of type DnqPrintService.
      • The broker must have read and write access to it.
      If the print output must be kept secure, specify an output directory to which access is restricted. Access to the directory /tmp is usually not restricted.
    PrintOptions <Options>
    The meaning of this attribute depends on the printer device type:
    • If PrintDeviceType=0 (PrintToPrinter), this attribute specifies the name of a CO of type DnqPrintOutputDescriptor. This CO must already exist, and is used to create the output descriptors for this print queue. These output descriptors determine the printer to which the output from this print queue is sent. Each output descriptor that is created is given the same name as the CO.

      If the value of the attribute PrintOptions contains the name of an external configuration file, for example: /home/myprt.xml, this file will be used and the definitions overwrite the customized values for the print queue. The configuration file must be readable for the broker started-task user ID.

    • If PrintDeviceType=1 (PrintToFile), this attribute specifies the prefix to be added to the name of each print output file.
      When printing an order to a file, the name of the output file is generated automatically by the message printing service, and has the form: 
      <prefix><ou>_<printQueueName>_<ordersn>_<timestamp>.prt
      where:
      <prefix>
      The value assigned to the PrintOptions attribute. Note that, if you want an underscore to appear before the name of the OU, you must specify it explicitly as part of this value.
      <ou>
      The name of the OU for which the print output file is to be generated.
      <printQueueName>
      The name of the print queue to which the order belongs.
      <ordersn>
      The sequence number of the order.
      <timestamp>
      Date and time, in Coordinated Universal Time (UTC), when the message printing service generated the output file. The format is YYYYMMDDHHMMSS.
      For example, if the PrintOptions attribute is set to Main_, and the message printing service generates the output file for BANKA, print queue 'PrintQFile', and order sequence number 100291 on 31 August 2022 at 14:05:32 (2:05:32 P.M.) UTC, then the generated output file has the following name:
      Main_BANKA_PrintQFile_100291_20220831140532.prt
    PrintLineLength <LineLength>
    Specifies how many characters are to be printed per line. This must be a number from 1 to 999. The default is 80.
    PrintPageLength <PageLength>
    The number of lines that the printer is able to print per page. This must be a number from 1 to 999. The default is 60.
    PrintFormatHeader <FormatHeader>
    A message printout can include either or both of the following types of information included in the MQRFH2 header of the message:
    History information
    This is the contents of the ComIbmDni.History folder in the MQRFH2 header of the message. History information is printed in front of the message itself. An example is included below:
    
⋮
Message History
--------------------------------------------------------------------------------
UTC timestamp: 20220130 091602
Service      : SDF
Function     : IMPORT
Result       : Ok
User         : test
Queue        : T1.BANKA.DNF_ILC_FIN
Destination  :
--------------------------------------------------------------------------------
⋮
    Context information
    Depending on the message type and if the information is available in the MQRFH2 header, the context section contains the information as listed in Table 1. Context information is printed in front of the message itself. An example is included below:
    
⋮
================================================================================
Context Information

OU: BANKA              Msg ID: 414d5120444e49514d20202020202020d65fb9621e00e625
Local address : ou=local,o=ptsadeff,o=swift
Remote address: ou=remote,o=ptsadeff,o=swift
Network String: 
-------------------------------------------------------------------------------
MESSAGE SEND REQUEST

TransferOptionSet: TOS_SET1
Service          : swift.test.sf.iafa!x
RequestType      : admi.xxx.ia.rma.001
MsgRef           : RequestRef
Dup Ref          : 
Dup Info         : 
CompletionCode   : Ok
...............................................................................
Reason Code: Ok
⋮
    The PrintFormatHeader attribute specifies which information is to be included in the printout:
    Value Description
    0 Do not include history information or context information.
    1 Include history information but not context information.
    2 Include context information but not history information.
    3 Include both history information and context information. This is the default.
    The context information will contain the following:
    Table 1. Context information for print output
    Field FIN Message Send Request Message Received notification Message DeliveryAck notification Comment
    OU X X X X  
    Msg ID X X X X The MQ message identification.
    External Msg-ID X X X X External message ID.
    Local address X X X X  
    Remote address X X X X  
    Network Code X X X X  
    Network String X X X X  
    Comment X X X X Content of Dnq/ER/Comment.
    FIN X       If the Dnf folder is available (Y or N).
    FMT X       If the Dnf folder contains FMT information (Y or N).
    MsgDigest X        
    FINCopyDigest1 X        
    FINCopyDigest2 X        
    MergedACK X       If merged acknowledgments are used.
    TransferOptionSet   X      
    Service   X X   Content from /TransferOptions.
    RequestType   X X   Content from /TransferOptions.
    MsgRef   X X   Content from /AppHdr/MsgRef.
    Dup Ref   X X   Content from /AppHdr/Dup/Ref.
    Dup Info   X X   Content from /AppHdr/Dup/Info.
    CompletionCode   X X X The completion code.
    Reason Code   X X X The information available in the ReasonList folder.
    Reference       X Content from /Notification.
    Notif.-Ref       X Content from /Notification.
    Notif.-State       X Content from /Notification.
    SnfRef       X Content from /Notification/NonDelivWarning.
    Code       X Content from /Notification/NonDelivWarning.
    PrintFormatMessage <FormatMessage>
    This attribute specifies how the content of a message should be formatted in the printout:
    Value Description
    0 Formatted output. Print all fields of each message.
    1 Formatted output. Print only those fields that contain values. This is the default.
    2 Line format output.
    OrderSize <OrderSize>
    This attribute specifies the number of messages that are to constitute a single print job. When the order size is reached, the order is processed and a corresponding print job is submitted. The order size must be a whole number that is greater than 0. Because the processing of a large order can significantly and adversely affect the availability of system resources, setting an order size larger than 1000 is not recommended. The default is 1.
    OrderTimeout <OrderTimeout>
    This attribute specifies the number of minutes after which an order is processed regardless of whether its order size was reached. The default is 0, which deactivates the timeout and causes the print order to be printed only when its order size was reached.
    Confirmation
    This pseudo attribute indicates whether manual confirmation for print orders is required. If this attribute is specified, each order must be confirmed manually as correct and complete after it was printed. Messages are considered to be in process until the confirmation was done.
    BICExpansion
    This pseudo attribute indicates whether the following information, which is contained in the FTM SWIFT reference data database, is added to the printout for each message:
    • Institution name of each BIC
    • Location of each BIC
    • Branch information about each BIC
    Priority <Priority>
    Priority of the print queue. This must be a number from 0 to 9, with 9 representing the highest priority. The default priority is 5.
    TargetQueue <TargetQueue>
    This attribute specifies the queue into which the message printing service is to place messages after it finished processing them. If this attribute is not configured, the messages are not exported after printing.
    TargetQMgr <TargetQueueManager>
    This attribute specifies the queue manager of the target queue. The default is the queue manager used by the message printing service.
  4. Run the modified copy of the ou_dnqcpcqo.cli script. This requires the access rights provided by the system configuration administrator (DniSA) role: 
    dnicli -i instance -ou SYSOU -s DNI_SYSADM -cf ou_dnqcpcqo.cli
  5. Approve and deploy the changes: 
    dnicli -i instance -ou SYSOU -s DNI_SYSADM
app -ou ou
dep -ou ou
If dual authorization is enabled, another user with the appropriate access rights must approve the changes before they can be deployed. If dual authorization is disabled, you can skip approving the changes and immediately deploy them.
Note: If you change the configuration of a print queue, you must stop and restart the queue to activate the change.