$RCSfile: README,v $
-------------------
cvs         : $Id: README,v 1.6 2004/01/19 18:53:50 aquamaniac Exp $
begin       : Mon Oct 13 2003
copyright   : (C) 2003 by Martin Preuss
email       : martin@libchipcard.de



 This file describes the format of the HBCI-XML files.
 Some facts about these files are hard to describe, so please consult the
 accompanying HBCI XML files in parallel to this README.

 If you want to use a JOB defined in the files for your application you
 need to know which data elements this job needs or returns.
 Please use the tool "hbcixml" for this purpose.



 Files used
 ----------
 OpenHBCI uses one HBCI file: "hbci.xml"
 This file contains definitions for all HBCI versions.


 About Tags
 ----------
 This file contains some main tag groups. Each group contains a list of
 subtags which have the same name as the group itself with the suffix "def".
 - <GROUPS>
   Here some basic groups are defined (by means of <GROUPdef> tags)
 - <SEGS>
   This group contains HBCI segment definitions (<SEGdef> tags)
 - <JOBS>
   This group contains HBCI job definitions (<JOBdef> tags)

 Within each <XYZdef> tag you may refer to another group or segment
 by including a tag (like <GROUP> or <SEG>). The group or segment you refer
 to is given by the property "type".

 You can also include <ELEM> tags which describe a single data element (see
 the HBCI files for clarification)

 If you want some data elements (<ELEM>) to be preset with reasonable data
 you may insert a <VALUES> tag into any group/segment. Such a group contains
 a <VALUE> tag for each data element to preset.
 
 Example:
 You want to refer to the group "btg", so the tag to use is
 <GROUP type="btg" />
 
 This will include the given group in your current group (in which you placed
 the tag above).
 That group must be declared like this:
 <GROUPdef id="btg">...</GROUPdef>



 General properties:
 --------------------
 "type"       type of the element or group. 
              For groups the type is the name of another group to be included
              within the current group.
              For elements the following types are allowed:
                "an"    (alphanumeric)
                "alpha" (alpha only)
                "num"   (numeric only)
                "float" (floating point numeric)
                "ascii" (all characters)
                "bin"   (binary data in HBCI-format: @SIZE@DATA...)
 "bintype"    if "type" is "bin" then this property allows specifying the
              type of binary data.
              OpenHBCI will try to locate the corresponding parser plugin
              with that name to parse such a data element (e.g. "swift" for
              parsing SWIFT data)
 "binsubtype" if "type" is "bin" then this property allows closer
              specification of data type (e.g. "mt940" for a SWIFT MT940
              data element).
 "name"       name of the group or element. If a name is given this is used
              as a group- or varname when looking up ariables
 "id"         this is used when defining a group. It is the name to be used
              as "type" when including another group within a group.
 "topdown"    if "1" then value definitions (declared in <VALUES> tags)
              from higher levels override those of lower levels. This 
              property only applies to the <ELEM> it is defined in. 
              If you use "1" then the definitions inside an element are only
              used as a fallback, when no higher level defines those values.
 "leftfill"   (only for type "num"): fills a number with leading "0"s
 "rightfill"  (only for type "num"): fills a number with trailing "0"s
 "minnum"     minumum number of occurrences for a given element or group
 "maxnum"     maxumum number of occurrences for a given element or group
 "minsize"    minimum size of the data (e.g. minimum length of a string)
 "maxsize"    maximum size of the data (e.g. maximum length of a string)
 "trustlevel" this is used to anonymize sensitive data when creating bug 
              reports. The higher this level the less likely it is that this 
              element will be logged. 
              The default value "0" means that the element actually GETS 
              logged. We have the following levels:
                "0" no trust needed to log
                "1" low trust needed to log
                "2" medium trust needed to log
                "3" high trust needed to log
                "4" full trust needed to log
 "mode"       "DDV" or "RDH". If omitted then the group with this property can
              be used in either mode
 "delimiter"  the character given by this property is used to divide a
              message into single elements and groups. HBCI uses
              "+" between DEs and ":" between DEGs
 "terminator" that's not the governour of California, this character is
              used to terminate a segment. In HBCI this is "'".
 "hide"       if "1" then the tool hbcixml will not show this group/element
              (defaults to "0")



 Special properties for segments:
 ---------------------------------
 "isbpdjob"   marks the segment as a BPD job description (which holds
              parameters for a job). Those descriptions are sent by the
              institute as a response to dialog opening jobs
 "code"       contains the HBCI code of a segment (such as "HNHBK" for the 
              message head).
 "version"    segment version. See HBCI specs for the versions of each
              segment
 "pversion"   HBCI protocol version this segment applies to. This information
              is used when creating a HBCI message.
              Note: Only those segments and jobs should have this property
              which do NOT have BPD job description (like JOBGetKeys etc.) !
              Other jobs for which such a description exists (like
              JOBGetBalance) should not have this property !
              This is because if a job has a BPD job description OpenHBCI can
              extract the information about the segment version to be used 
              from that description.
              If no such description exists for a given job OpenHBCI needs
              another hint which segment version to use so it uses the
              "pversion" property.



 Special properties for Jobs:
 -----------------------------
 "single"     "1" if the job wants to be alone inside a message 
              (default is "0")
 "attachable" "1" if the job uses an attachment point (this is for jobs
              which may get a partial response, in which case the same jobs
              has to be sent again and again as long as an attachment point
              is returned (->"Aufsetzpunkt") (default is "0")
 "crypt"      "1" if the job needs encryption (default is "1")
 "sign"       "1" if the job needs signing (default is "1")
 "dlg"        "1" if this job has its own dialog opening and closing
              messages (default is "0")
 "needbpd"    "1" if this job needs a BPD job description (default is "0")
 "params"     code of the segment containing the BPD job description
              (e.g. "HISALS" for job "JOBGetBalance")



 <VALUE> Tags
 ------------
 In <VALUES> groups you can use property and global variable names as the 
 source of data.
 Values in a <VALUES> group are only used as a fallback. If the user already
 provided all the data needed for a segment to be build then these values here
 are not used.
 If the first character of the data to <VALUE> is one of the following, then
 the data will be translated accordingly:
 "%NAME" use the local property of the given name (this property will be
         looked up in the tag's property list)
 "$NAME" use the global variable of the given name (this variable will be
         looked up in the variable list of the message engine)
 "+NAME" like "$NAME", but additionally post-increments the variable.
         NOTE: This does not work with elements with the property "topdown".
         In this case if the data for the element is defined in a level above
         then this value here would be incremented even while not used !
 "?NAME" use a customer value. The value of this variable is taken from the
         customer who owns the job of which this segment is a part, like:
         -customerid
         -userid
         -systemid
         -bankcode
         (TODO: define more variables for this)



 Some global variables:
 ------------------------
 The following variables are used internally. This section is only for
 information purposes, you should not use these variables when creating
 new job definitions !
 
 "SegmentNumber"
    This global property is incremented after a segment has been created. So
    each segment gets its own number within a message
 
 "DialogId"
    This property holds the dialog id assigned to the current dialog by
    the server. OpenHBCI automatically keeps track of this property.
    Upon connection opening "0" is used. When the server responds, then
    it sends a new dialog id which is from then on used by OpenHBCI for
    the current dialog.



 Creating new jobs/segments
 ----------------------------
 Please look into hbci.xml for examples of jobs/segments.
 It is quite easy to follow them ;-)


Martin Preuss, Hamburg, Jan 18 2004



