      ******************************************************************
      *
      *     Interface to called user-defined format handling module
      *
      ******************************************************************
      *
      *  The user format routine provides a mechanism to allow the
      *  definition of the behaviour of input to a field different from
      *  the standard ways Dialog System offers. This is achieved by a
      *  COBOL program written to interface to the Dialog System run
      *  time software.
      *
      *  The interface to this module has two parameters; a control block,
      *  and the field buffer. Ie. Internally the module is called from
      *  the Dialog System run-time software as follows:
      *
      *        CALL "DSUSRFMT" USING DS-USER-LINKAGE DS-FIELD-BUFFER.
      *
      * ************* NEW FORMAT in DS2.5.64 *******
      *
      *  When specifically enabled in the sidefile dsdef.cfg, then the
      *  call from the Dialog System run-time includes an additional
      *  parameter - the user data block. It is the user's
      *  responsibility to not access beyond the end of this data
      *  block.
      *
      *  This new feature allows decisions in DSUSRFMT to be based upon
      *  the content of other data items. One use is in allowing
      *  unlimited field protection, by inspecting a data flag
      *  corresponding to the current field on initial field entry, and
      *  simply autoskipping out of the field if the flag indicates
      *  that it is in a protected state.
      *
      *        CALL "DSUSRFMT" USING DS-USER-LINKAGE DS-FIELD-BUFFER
      *                                              DS-DATA-BLOCK.
      *
      * ************* NEW FORMAT in DS2.5.64 *******
      *
      *
      *  DS-USER-LINKAGE is described below.
      *
      *  DS-FIELD-BUFFER is of variable size depending on the current
      *  field being input. It contains the current value of the field
      *  complete with decimal point if neccessary. It is important to note
      *  that this buffer may be larger than the size of the field on the
      *  panel. It is advised to use reference modification to modify this
      *  field and at no time should an attempt be made to access any part
      *  of this field greater than the current field size otherwise
      *  unpredictable results may occur.
      *
      *  The control block is split into two parts. Those fields which
      *  provide information to the user format module and those fields
      *  which provide information and also control subsequent behaviour.
      *
      *  Input Fields:
      *
      *    Ds-Access-Flag
      *
      *      The user format routine will be called with one of four
      *      different accesses at different points when running the
      *      screenset.
      *
      *        ds-load-access      - When the screenset is initialised.
      *        ds-initialise-Field - When a field is to be set to its
      *                              default state. This is whenever the
      *                              panel fields are refreshed eg. during
      *                              an RFTD function or a POP, or before
      *                              the first key stroke is pressed when
      *                              moving on to a field for input.
      *        ds-normal-access    - After each keystroke during input in
      *                              to the field.
      *        ds-Terminate-Field  - If the field is completed. This is
      *                              usually when a key with dialog has
      *                              been requested or the user format
      *                              routine has requested to move on to
      *                              another field.
      *
      *    Ds-Screenset-Name
      *
      *      The name of the current screenset.
      *
      *    Ds-Screen-Name
      *
      *      The name of the current panel.
      *
      *    Ds-Field-Name
      *
      *      The name of the current field if not greater than 8 characters,
      *      otherwise contains '@' in first character position. The full
      *      name can always be found in Ds-Field-Long-Name.
      *
      *    Ds-Field-Offset
      *
      *      This gives the position of the field on screen. This is
      *      the same for both PANELS or Non-Panels mode starting at
      *      an offset of zero.
      *
      *    Ds-Field-Screen-Length
      *
      *      This is the length of the field on the panel. This does not
      *      include the sign if present.
      *
      *    Ds-Master-Format
      *
      *      The format of the current field in the data block. (See data
      *       block Formats below).
      *
      *    Ds-Screen-Format
      *
      *      The format of the current field on the panel. (See screen formats
      *      below).
      *
      *    Ds-Screen-Subformat
      *
      *      It is possible for some screen formats to have subformats . This
      *      applies to date and numeric fields. (See screen subformats below).
      *
      *    Ds-User-Format-Number
      *
      *      The user format number of the current field.
      *
      *    Ds-Length
      *
      *      For numerics this is the length of the integer part of the field.
      *      For other types this gives the length of the field.
      *
      *    Ds-Decimal-Length
      *
      *      For numerics this gives the length of the decimal part of the
      *      field. This will be zero for other field types. The length does
      *      not include the decimal point.
      *
      *    Ds-Sign
      *
      *      When set to 1 this signifies the presence of a sign with this
      *      field on the panel.
      *
      *    Ds-Buffer-Length
      *
      *      This is the length of the formatted buffer passed from Dialog
      *      System to the user format routine.
      *
      *    Ds-Shift-State
      *
      *      This gives the current state of the shift keys by looking at the
      *      bits of the byte provided along the following lines:
      *
      *        Current state of shift keys.      1 = on   0 = off
      *
      *        bit     7    6    5    4    3    2    1    0
      *                --- not used ---   ALT  CTL  LSH  RSH
      *
      *    Ds-Lock-State
      *
      *      This gives the current state of the Lock keys by looking at the
      *      bits of the byte provided along the following lines:
      *
      *        Current state of lock keys.       1 = on   0 = off
      *
      *        bit     7    6    5    4    3    2    1    0
      *                --- not used ---   INS  CAP  NUM  SCRL
      *
      *  Output Fields:
      *
      *    Ds-Cursor-Position
      *
      *      The current position of the cursor within the field on the panel
      *      starting from position 1. This should not exceed the value of
      *      Ds-Field-Screen-Length otherwise the cursor will appear outside of
      *      the current field.
      *
      *    Ds-Sign-Value
      *
      *      This gives the current value of the sign of the field. 1 means
      *      positive, zero negative. This only applies to numeric fields.
      *
      *    Ds-Buffer-Screen-Offset
      *
      *      This gives the offset of the first character in the field buffer
      *      that is to be shown in position 1 of the current field on the
      *      panel. This offset starts from 1.
      *
      *    Ds-Display-Field-Flag
      *
      *      This informs Dialog System to redisplay the current field.
      *      This will also update the sign if one is present.
      *      A value of 1 means do the display, 0 means no display.
      *      Dialog System sets this value to 01 by default after each key
      *      stroke.
      *
      *    Ds-Display-Cursor-Flag
      *
      *      This informs Dialog System to redisplay the cursor at the
      *      position given by Ds-Cursor-Position.
      *      A value of 1 means do the display, 0 means no display.
      *      Dialog System sets this value to 0 by default after each key
      *      stroke.
      *
      *    Ds-Autoskip-Left
      *
      *      This informs Dialog System to leave the current field and move
      *      to the previous input field.
      *      A value of 1 means go to previous field, 0 means do nothing.
      *      Dialog System sets this value to 0 by default after each key
      *      stroke.
      *
      *    Ds-Autoskip-Right
      *
      *      This informs Dialog System to leave the current field and move
      *      to the next input field.
      *      A value of 1 means go to previous field, 0 means do nothing.
      *      Dialog System sets this value to 0 by default after each key
      *      stroke.
      *
      *    Ds-Do-Internal-Formatting
      *
      *      This flag signifies whether Dialog System is to perform its
      *      own formatting routines according to the screen format of
      *      the current field. This allows the user format routine to
      *      slighltly modify the input behaviour of a field but not have to
      *      provide all the field handling code.
      *      A value of 1 means do the internal formatting, 0 means do nothing.
      *      Dialog System sets this value to 1 by default after each key
      *      stroke.
      *
      *    Ds-Input-Key.
      *
      *      The two fields below describe the last key pressed. The copy
      *      file DS-KEY.CPY gives constant declarations for the required
      *      values. The value of the key can be changed to pass Dialog
      *      System a different key to the one that was actually pressed.
      *
      *      Ds-Key-Type        - The type of key pressed. This is one of
      *                           function key, data key, shift key or lock
      *                           key.
      *
      *      Ds-Key-Description - Further information to give the exact key
      *                           within the key type.
      *
      *    Ds-Field-Panel-Offset
      *
      *      This gives the position of the field on panel. In non-panels
      *      mode this is the offset starting at position zero on the full
      *      screen.
      *      In MF-Panels mode this is the offset starting at zero within the
      *      current panel.
      *
      *    Ds-Field-Long-Name
      *
      *      This holds the name of the data field.
      ******************************************************************
      *
      * CONSTANTS
      *
      ******************************************************************

      *
      * Access codes
      *

       78 Ds-Load-Access                        VALUE "L".
       78 Ds-Initialise-Field                   VALUE "I".
       78 Ds-Normal-Access                      VALUE "C".
       78 Ds-Terminate-Field                    VALUE "T".

      *
      * Data Block formats
      *

       78 Ds-Alphanumeric                       VALUE 1.
       78 Ds-Alphabetic                         VALUE 2.
       78 Ds-Numeric                            VALUE 3.
       78 Ds-Signed-Numeric                     VALUE 4.

      *
      * Screen formats
      *

       78 Ds-Screen-Date                        VALUE 0.
       78 Ds-Screen-Numeric                     VALUE 50.
       78 Ds-Screen-Alphabetic                  VALUE 100.
       78 Ds-Screen-Alphanumeric                VALUE 150.

      *
      * Screen sub formats for date fields
      *

       78 Ds-Date-xx-xx-xx                      VALUE 1.
       78 Ds-Date-xx-xxx-xx                     VALUE 2.
       78 Ds-Date-xx-xxx                        VALUE 3.
       78 Ds-Date-xx-xx                         VALUE 4.
       78 Ds-Date-xx-xx-xxxx                    VALUE 5.

      *
      * Screen sub formats for numeric fields
      *

       78 Ds-Zero-Suppressed                    VALUE 2.

      *
      * Screen user formats
      *

       78 Ds-User-Fmt-1                         VALUE 1.
       78 Ds-User-Fmt-2                         VALUE 2.
       78 Ds-User-Fmt-3                         VALUE 3.
       78 Ds-User-Fmt-4                         VALUE 4.

      **************************************************************************
      *
      * User Format Program Linkage Section.
      *
      **************************************************************************

       01 Ds-User-Linkage.

      *  Fields providing information to the user format routine which can
      *  not be modified.

         03 Ds-Access-Flag                      pic x.

         03 Ds-Screenset-Name                   pic x(8).
         03 Ds-Panel-Name                       pic x(8).

         03 Ds-Field-Name                       pic x(8).
         03 Ds-Field-Offset                     pic 9(4) comp.
         03 Ds-Field-Screen-Length              pic 9(4) comp.
         03 Ds-Master-Format                    pic 9(2) comp.
         03 Ds-Screen-Format                    pic 9(2) comp.
         03 Ds-Screen-Subformat                 pic 9(2) comp.
         03 Ds-User-Format-Number               pic 9(2) comp.
         03 Ds-Length                           pic 9(4) comp.
         03 Ds-Decimal-Length                   pic 9(2) comp.
         03 Ds-Sign                             pic 9(2) comp.

         03 Ds-Buffer-Length                    pic 9(4) comp.

         03 Ds-Shift-State                      pic 9(2) comp.
         03 Ds-Lock-State                       pic 9(2) comp.

      *  Fields providing information to the user format routine which can
      *  also be modified to control the behaviour of Dialog System.

         03 Ds-Cursor-Position                  pic 9(2) comp.
         03 Ds-Sign-Value                       pic 9(2) comp.
         03 Ds-Buffer-Screen-Offset             pic 9(4) comp.

         03 Ds-Flags.
            05  Ds-Display-Field-Flag           pic 9(2) comp.
            05  Ds-Display-Cursor-Flag          pic 9(2) comp.
            05  Ds-Autoskip-Left                pic 9(2) comp.
            05  Ds-Autoskip-Right               pic 9(2) comp.
            05  Ds-Do-Internal-Formatting       pic 9(2) comp.

         03 Ds-Input-Key.
            05  Ds-Key-Type                     pic 9(2) comp.
            05  Ds-Key-Description              pic 9(2) comp.
            05  Ds-Key-Description-X REDEFINES
                        Ds-Key-Description      pic X.
            05  FILLER                          pic 9(2) comp.

         03 Ds-Field-Panel-Offset               pic 9(4) comp.
         03 FILLER                              pic x(8).
         03 Ds-Field-Long-Name                  pic x(30).
