Document Structure

Three rules are required for each letter (“documentheader”, “document”, “documentfooter”), which print in the respective page area of the document. You find them in the “Module Explorer” under “Rules\ Document Rules”. In exceptional cases (e.g. in internal letters or reply letters) it is possible that fewer than three rules are sufficient.

Tip: The unused rule does not have to be available. However, it makes sense to keep this unrequired “documentheader/documentfooter” rule, but without the relevant lower-level subrule; e.g. “XMLPrintHeader” If the “documentheader/documentfooter rule” is ever amended to include an appropriate comment explaing why this XML panel does not need to have a header/ footer, the rule becomes easily comprehensible.

This rule usually launches the “XMLPrtHeader” rule because the header area of each bank and the Output Channel remains almost unchanged in all messages. In this area, the logo (on the left) and the sender information (on the right) are displayed by default.

“XMLPrtHeader” contains the following Subrules:

• “XMLGetLogo” - Determines the logo to be used
• “XMLGetOwnAdr” - Determines the sender information for the first page
• “XMLGetDate” - Provides location and date
• “XMLGetDepartment” - Determines department / business sector
• “XMLGetUser” - Provides information about the clerk
• “XMLGetHdrRef” - Determines the sender information for the following pages

At first the Logo has to be copied into the respective directories “\FRAME\<Language>\” as “*.GIF” files with the same name (i.e. you can choose a different logo for each language). The rule “XMLGetLogo” reads out the file name either from “SYSMOD\ETY\LETLOG” (separate logo for letters) or from “SYSMOD\ETY\OFFLOG”. Of course, the logos need to have been properly mapped to the respective entity (via Entity Maintenance).

This is where the actual message begins (mostly the individual part). This rule initiates the output of the Postal Notice with address field (recipient), subject line, salutation, actual message and complimentary close.

Postal notice, recipient address, subject and salutation will be displayed via the following rules:

• specific area: “xxTMOD\xxTDOC.XMLDocStartxx”, z.B. “LITMOD\LITDOC.XMLDocStartLI( <Dokumententitel> )”.
• all areas: TRNMOD\TRNDOC.“XMLDocStart( <Dokumententitel> )”

The rule for the specific area should be used. Transactions that create a subcontract should use “XMLDocStart-” Regel of the subarea (e.g. BRTMOD\BRTDOC.XMLDocStartBR( <Dokumententitel> ).

“DocStart[XX]” contains individual subrules:

• “XMLPrtAdrOfReceiver” - Output of postal notice and recipient address
• “XMLPrtTitleBold( <Document Title> )” - Output of the document title
• “XMLPrtRefBlk[XX]” - Output of references
• “XMLPrtSalutation” - Output of salutation

These rules provide the single components separately.

The individual (main) part, i.e. the actual content of the message, is programmed directly within the “document” rule using XML elements. However, if it is reasonable, it is also possible that it will be (partly) centralized.

Tips:

• Introduction text for each message
  It is advisable to write the introduction text of the message in an XML element called “Intro<content>” (e.g. IntroAdviceToBEN). Thus, it is easy to understand, that it is an introduction text. In German, after the salutation “Sehr geehrte Damen und Herren” the text continues in small letters. In English, after “Dear Sirs” the text continues with a capital letter. This type of usage saves a translator (who translates the messages with a tool outside the transaction) a lot of time and mistranslations will also be avoided.
• Simple, clearly structured texts
  Texts in an XML element should be structured as simple as possible and should normally not contain more than 2 variables. In case multiple fields are to be displayed, it is recommended to display those in a list. When displaying variables it has to be considered, that the fields are filled and that accordant “If isempty” queries are implemented, if applicable.
• Readability even for non-programmers
  Rather copy the contents of XML elements that contain customized texts than creating complicated new texts.
• Texts within the XML elements
  The message texts should preferably be within XML elements. 'Assembling' a cloze text with variables outside the XML element should be avoided at all costs, as such a construction is difficult to read and can only be translated cumbersomely into other languages.
• Comments have to be written for items which are not self-explanatory
  

The following calls make up the end of the “document” rule:

• XMLPrtTxtBlk( TRNMOD\TRNDOC\DOCCUR\ADDTXT ) for displaying the Sender-To-Receiver text from the Messages Details Panel, if filled
• SETMOD.PrintSettlement ( TRNMOD\TRNDOC\DOCCUR\ROLE ) for displaying the fees and settlement details, if available for the receiver of the message
• TRNMOD\TRNDOC.XMLPrtAPPRUL ( xxDGRP\REC\APPRUL, xxDGRP\REC\APPRULTXT ) for displaying the applicable rules, if available in the contract
• XMLDocEnd( ”<Argument>“ ) for displaying the salutation and the note for attachment(s).

Generally, in this area only the rule “XMLPrtFooter” is called, because the footer area is identical in almost every letter. This rule controls, for example, the page numbers. It can also be used to display the court of jurisdiction or the like.

Subrules creating direct outputs via “print using”, always start with ”“XMLPrt…”“. Note: Names have to be self-explanatory and as short and easy as possible.

Blank lines belong logically to the preceding element. Only the current element 'knows', if a blank line follows or not. A blank line is created by calling “XMLPrtEmptyLine” because they can easily be forgotten during the translation, which can result in hardly traceable effects. A “XMLPrtEmptyLine” is also responsible for a correct page break.

• General elements (e.g. elements, that are always inserted as separate paragraph into a document) (i.e. that are contained in a “subrule”) will immediately be added a blank line. In this way, the elements are contained in the subrule and always available.
• No blank lines are added to XML elements, which can be randomly combined with other XML elements (i.e. they do not have to create an own paragraph). If necessary, the blank lines have to be defined in the rule calling this element.

A page break in its simple form is created by the commands “print pagebreak” or “print FF” (for form feed). In this way, a command for an immediate start of a new page is given out in the created text.

A conditional page break can be achieved by using “print pagebreak ( <Length>, <Unit> [, <Reference Point> ] )”. A command for the start of a new page in the created text will be given out, if the parametric conditions do not match at that point in time, when the documents are formatted.

The effect of the function depends on the <Reference Point> parameter value. If this value or “tdSpaceRemaining” is not specified, the <Length>/ <Unit> define the remaining space on the page, which has to be at least available, in order to call “print pagebreak” at that point. If the remaining space is less than the given value for <Length>/ <Unit>, a page break will be carried out. Otherwise the command will be ignored.

If you use “tdPosAbsolute”, <Length>/ <Unit> defines the maximum distance to the top edge of the page. If this value will be exceeded, a page break will be inserted. Otherwise the command will be ignored.

“print pagebreak” take only effect in the body area (“document” rules). This is the main area of the document. Its text is distributed over several pages. “The print pagebreak” commands being used within “beginarea … endarea” do not have any effect.

With the commands “print protect( TRUE )” and “print protect ( FALSE )” you can protect areas in the document against cutting off texts via page breaks. Such a group of text outputs will be displayed on the following page, if it does not (quite) fit on the current page as a whole. If the text of the whole group does not fit completely on the next page, a page break to the following pages will then be inserted.

“print protect” has the same effect like “print protect ( TRUE )”.

“print protect ( FALSE )” ends a block which was started with “print protect ( TRUE )”.

Every call of “print protect ( TRUE )” ends the preceding block that was protected.

The behavior of XML elements during formatting can be defined on the “Cell” tab of the “XML Properties” editor. These properties can only be set for single-column XML elements.

The default values are read out as ”*.XSI“ file. For the page break these values are visible in the area “Page-break”.

The property “Orphans” defines the minimum number of lines of an output block at the end of a page. If it is not defined, the whole block will be moved to the following page.

The property “Widows” defines the minimum number of lines of an output block at the beginning of a page. If it is not defined, the whole block will be displayed on this page.

“keep with next”: The XML element will be combined with its immediate successor in the output to a logical output block. The properties “Orphans” and “Widows” apply to the whole block. The “Orphans/Widows” value of the group is defined as maximum of all individual values for Orphans/ Widows in a group.

“keep with previous”: The XML element will be combined with its immediate predecessor in the output to a logical output block. The properties “Orphans” and “Widows” apply to the whole block. The “Orphans/Widows” value of the group is defined as maximum of all individual values for Orphans/ Widows in a group.

From the technical point of view “keep with next” and “keep with previous” are identical. Before the actual document formatting they are transferred into one of both cases.

In the MyModelbank there is an example for this case in the rule “XMLDocEnd”.

If the salutation or another part [enclosure(s)] is moved to the following page, the last two lines of the preceding text shall always be displayed on top of the following page. At first, the XML elements “EncInf” (single-line), “emptyline” (single-line) and “DocEnd” (double-spaced) are connected to each other via “keep with previous”. Altogether the salutation has a length of 7 lines (because of the 4 blank lines). To get the two lines of the preceding page plus one blank line onto the following page, the property “Widows” has to be adapted (Standard: 2). The new value for “EncInf” will then be 10 lines (7+3). If there are no enclosures, only “DocEnd” is displayed; wherefore the new values is 5 lines (2+3).

Of course, now it has to be ensured that the rule “XMLDocEnd” will be used in every “document” rule. Otherwise the control function would only be limited.

Apart from that, the property “Widows was increased for emptyline” up to 3 lines. In this way, every text block that will be moved sometime and which will be added this blank line via “XMLPrtEmptyLine”, will also be moved with two visible lines (i.e. 2 lines + 1 blank lines).

General rules are defined in “TRNMOD\TRNDOC”. Moreover they have to be declared as “global”, “static” or “method”. These rules are merely called via their names and paths (if necessary).

Examples for available rules:

• “XMLFmtAmount( <Amount>, <Currency> )” - formats an amount in the message language
• “XMLFmtCurAmt( <Currency>, <Amount> )” - formats currency and amount in message language, with a protected space
• “XMLFmtDate( <Type>, <Date> )” - formats the date in message language
• “XMLGetNomSpc” - Output of amount tolerance and amount specification
• “XMLGetPtyNam( <Party> )” - determines name and location of a party in a line (e.g. RMDGRP\ISS)
• “XMLGetRoleDesc( <Role> )” - determines the role via the table 'ROLALL' (e.g. 'ISS')
• “XMLGetTblText( <Key>, <Table> )” - determines the longtext of a key from a specific table in the message language
• “XMLGetTxtSepTxt( <Text1>, <Delimiter>, <Text2> )” - delimits 2 texts with a passed delimiter (e.g. comma, carriage return, etc.)
• “XMLPrintHeader” - Output of the letterhead
• “MLPrintFooter” - Output of the letter footer
• “XMLDocStart( <Title> )” - Output of the beginning of the letter
• “XMLDocEnd( <Enclosure> )” - Output of the end of the letter
• “XMLPrtEmptyLine( <Number> )” - Creates the desired number of Blank Lines
• “XMLPrtRefBlk -” Output of the subject block
• “XMLPrtRefLine( <Description>, <Field Content> )” - Output of a line of the reference block
• “XMLPrtRefLinePty( <Party> )” - Output of a line of the reference block (e.g. RMDGRP\ISS)
• “XMLPrtReplyStart” - Output of the beginning of reply letter>
• “XMLPrtReplyEnd” - Output of the end of reply letter
• “XMLPrtTxtBlk( <Field> )” - Output of a field with blank check and page break
• “XMLPrtTxtAboveBlk( <>Description>, <Field Content> )” - Output of description and field content located one below the other
• “XMLPrtTxtBeforeBlk( <Description>, <Field Content> )” - Output of description and field content located next to one another
• “XMLPrtTitleBold( <Title> ) -” Output of the letter title
• “XMLPrtClass_TRX” - Output of Postal Notice
• “XMLPrintQuoted” - Output of quoted text with begin/end hints of the quote
• “XMLPrtAPPRUL” - Output of the applicable rules
• “GetCurrentCORLineLength” - Determines the Output Channel
• “PtsGetCompressedAddress( PtsModGetAdrBlk( xxDGRP\<Role>) )” - Output of an address block without blank lines
• “SetDOCDAT” - sets the date of a letter for a specified document, e.g. 'Today + 1' for a letter sent by second post, or 'Date of earliest execution' for a transaction.

Area-specific rules are defined in “xxTMOD\xxTDOC” (e.g. “RMTMOD\RMTDOC”). These rules must have the property “method”. They are called via “xxTMOD\xxTDOC.<Rule Name>”.

Example for available rules:

• “XMLDocStartXX( <Title> )” (XX = Business Sector, e.g. “XMLDocStartRM”), because of the mostly individual reference blocks
• “XMLPrtRefBlkXX( <Title> )” (XX = Business Sector, e.g. “XMLPrtRefBlkRM”)

Rules that process the settlement of fees and amounts are defined in “SETMOD”

An existing rule is, for example:

• “PrintSettlement” - Output of the complete settlement

Rules that process data from the liability in order that they can be displayed accordingly in messages, are defined in “LIAALL”.

Examples:

• “XMLPrintSettledTenors” - Displaying the settled tenors (amount and maturity date)
• “XMLPrintTenorInfo” - Displaying the accepted future tenors without sight portion
• “XMLPrtTenors” - Displaying all individual tenors and sight portions with amount and maturity date (if available)

The following picture shows, in which rules the individual components of a message are processed.