TAA Tools
NTEFIL          NOTE FILE                              TAANTEA

The Note  File tool  lets you  add notes  (text) to  a data  processing
application.

For example,  assume you have a file of  customer records which contain
normal  data processing  fields.  When  a customer calls,  you may want
to add  some  text  regarding the  phone  call  or some  standard  text
associated with  the customer.   Adding text to normal  data processing
records  may  not be  desirable  and may  not be  open-ended  enough to
store the information you would like to capture.

The 'Note  File' tool  allows a  standard method  of  interfacing to  a
separate file  where 'notes' are kept.   The 'note  processing' program
maintains  the file and allows  end users to make  comments that can be
re-displayed, updated, and deleted.   The 'note processing' program  is
accessed via a CALL from  your application.  A small amount  of code is
required  in your  application to  interface  to the  'note processing'
program.   The same  'note file' may  be accessed from  several of your
application programs.

Each set of notes  is associated with a  unique key such as  a customer
number.  Two types of notes are possible:

   Master        The Master  note always  appears first when  a display
                 is  requested.    You  can  roll  to  see the  regular
                 notes.

   Regular       The regular notes  appear in LIFO  sequence.  You  can
                 have 9 notes per day per unique key.

When the  'notes' are  displayed, the user  can roll  up and  down thru
the  notes  for the  unique  key.   Depending  on options  set  by your
application program,  new notes  may be  added, existing  notes may  be
updated or deleted, master notes may be added, etc.

The best way  to understand the tool  is to try the  demonstration that
is available.

Demonstration
-------------

Assume  you  have a  customer  file  and you  want  to  add 'notes'  to
provide  a  master  note  for  some  customers  and  regular  notes for
certain transactions.   A  demonstration file has  been set  up with  5
unique customer numbers  and the file is initialized  with a few notes.
You  can add new notes, update or  delete existing notes, make a master
note, etc.

To use the demonstration, enter the command:

           DMONTEFIL

You will  see a  display that  allows you  to specify  which  of the  5
customers you want  to see the notes  for and the options  that will be
available when the notes are displayed.

During  the demonstration,  you decide what  options will  be available
when  the  'notes'  display  appears.    In  a  real  application,  the
programmer would  decide  what options  to make  available  to the  end
user.

Help text  is available from both the  demonstration display (seen only
in  the demonstration) and from the  'note processing' displays seen by
the end user.

You may change the  data in the file (DMONTEP)  as it is only  used for
the demonstration.  You may refresh the file with the command:

           CALL    TAANTEAC4

General comments
----------------

You  begin the implementation  of the  notes tool  by creating  a 'note
file' with the command:

          CRTNTEFIL    NTEFIL(yyyy/xxxx)

You  can have  as many  'note files'  as required.   In general,  it is
desirable to have a unique file per application area.

From any  of your  programs, you  call the  standard 'note  processing'
program and  pass it  a data  structure.   The data  structure must  be
filled with  various values that determine the  processing of the 'note
processing' program.

The normal  use  of the  'note  processing'  program is  to  leave  the
program and file open for  further use.  The program supports  up to 10
'note  files' that may  all be open  at the same  time.  Fields  in the
data   structure  describe  which  'note  file'   to  use.    When  the
application is  complete,  you can  close  the 'note  file'  associated
with  the application  or all  of the  open 'note  files' for  the job.
See the later discussion on opening and closing the 'note files'.

Old notes  can be manually deleted by an  end user if the DLTYES option
is specified.   You may  also run  the MTNNTEFIL  command which  allows
you to delete all  notes that are older than a specified  date.  Master
notes are never deleted with MTNNTEFIL.

Limits
------

  **   The unique key must be 30 bytes or less.

  **   The  number  of notes  per unique  key  or the  total  number of
       notes is only limited by the size of the file.

  **   One master note may exist per unique key.

  **   Up to  9 regular  notes may  be added  per day  per unique  key.
       See the later discussion of the Records in the Note File.

  **   Each note  is 14  lines of  75 bytes  per line.   Totally  blank
       lines  may appear within  a note.   The last non-blank  line for
       the  note determines how  much data will be  written to the data
       base.

  **   Up to 10 unique note  files may be open at the same  time within
       a job.

  **   Only  the first  member of  a  note file  is used  (multi-member
       files are not supported).

Program interface
-----------------

A  data structure  is used  for communication between  your application
and the standard  'notes processing' program  (TAANTEAR).  An  external
PF description  (TAANTEAX) is  provided for  the data  structure.   You
must  enter valid values into  several of the  processing fields before
you pass the data structure to the program.

The following code  is in the  correct format  to be copied  to an  RPG
program  to describe  the  data  structure,  fill the  required  fields
(described  later), and call  the 'notes  processing' program.   First,
use   CPYTAA   TAAARCMBR(NTEFIL)   to   copy   the   source   for  this
documentation member to QATTINFO in TAATOOL.

     I* Externally described data structure for 'note processing'
     INOTEDS    E DSTAANTEAX
     C****************************************************************
     C* Calculation specs to fill required fields
     C                     MOVEL'file nam'NEFILE           File
     C                     MOVEL'lib name'NELIB            Library
     C                     MOVEL'Dsp titl'NETITL           Title
     C                     MOVEL'unq key 'NENKEY           Unique key
     C                     MOVEL'ADDYES  'NEADD            Add option
     C                     MOVEL'UPDNO   'NEUPD            Upd option
     C                     MOVEL'DLTNO   'NEDLT            Dlt option
     C                     MOVEL'MSTYES  'NEMST            Master optn
     C                     MOVEL'DSP     'NEERR            Error option
     C                     MOVEL'DSP     'NEACTN           Action
     C                     MOVEL'Note txt'NEHTXT           Note text
     C****************************************************************
     C* Call the processing program
     C                     CALL 'TAANTEAR'                 Process pgm
     C                     PARM           NOTEDS           DS parm
     C****************************************************************

TAANTEAX Data Structure Field Descriptions
------------------------------------------

Unless otherwise specified, all values should be left adjusted.

   NEFILE        The file name  to be used.   The file must be  created
                 with the CRTNTEFIL command.

   NELIB         The  library where  the  file exists.    Blank is  not
                 valid.  A name, *LIBL, or *CURLIB must be used.

   NETITL        The  title  that  appears on  the  first  line  of the
                 'Notes' display.  You probably  want to enter a  value
                 that is  unique for  each application.   For  example,
                 you might  say 'Customer Notes'.   Up to 30 characters
                 may be entered.  If less  than 30 exist, you may  want
                 to offset the value  in the field to center  the title
                 on the display.

   NENKEY        The  unique  key  to the  set  of  notes.    Up to  30
                 characters may be entered.

   NEADD         Whether  to  allow  additional  notes  to  be entered.
                 ADDYES or ADDNO must be specified.

   NEUPD         Whether  to  allow  existing  notes  to   be  updated.
                 UPDYES or UPDNO must be specified.

   NEDLT         Whether  to allow  existing notes  to be  deleted with
                 the  F11  function  key.    DLTYES  or  DLTNO must  be
                 specified.   If the  user has  update capability,  the
                 user  can  delete  a  note by  blanking  out  all  the
                 existing  lines for the  note.   The command MTNNTEFIL
                 may also be used to delete old notes.

   NEMST         Whether to allow master records  to be added.   MSTYES
                 or MSTNO must  be specified.  If MSTYES  is specified,
                 ADDYES  must  also  be  specified.   Specifying  MSTNO
                 does  not  prevent the  display  of master  notes, but
                 the user is not allowed to add a new master note.

   NEERR         How to handle  error conditions.   DSP or RTNCDE  must
                 be specified.   If an  error occurs such as  'No notes
                 exist  for  the  unique  key',  this  field determines
                 whether a display will  appear or whether the  program
                 will return with the NERTNC value set to NOTFOUND.

                 For example,  you may want  to place an  indication on
                 your  normal application  display which  will describe
                 whether any  'notes' exist.   You  could use  the  RTV
                 action  code and  set  NEERR to  RTNCDE.   The  NERTNC
                 field  will be  set  to  FOUND or  NOTFOUND  after the
                 'note processing' program returns.

                 Other  errors are also possible  such as attempting to
                 add the 10th  note for a unique  key on the same  day.

   NEACTN        The  action  the  'notes  processing'  program  should
                 take.    The  normal interactive  solution  is  to use
                 DSP.    The  other  actions  allow  your   application
                 program  to communicate  with  the 'notes  processing'
                 program without  involving an end user.   For example,
                 you can have  a program that  processes in batch  that
                 adds or retrieves records from the 'notes file'.

                 One of the following must be specified:

                 DSP.  Requests  the 'display' function as seen  in the
                 demonstration.

                 ADD.   Allows the program to add a  regular note.  The
                 data  is passed  in the  NELN1-NELN14 fields.   If the
                 operation is  successful,  the  NERTNC field  will  be
                 set to ADDED.

                 ADDM.  Allows  the program to add a  master note.  The
                 data  is passed  in the  NELN1-NELN14 fields.   If the
                 operation is  successful,  the NERTNC  field  will  be
                 set to ADDED.

                 RTV.   Allows the program  to retrieve the  first note
                 (LIFO)  order for  a  unique key.   If  a  master note
                 exists, it  will  always  be  the  first  note.    The
                 NERTNC field will be set to FOUND or NOTFOUND.

                 RTVOPN.   Retrieves the  number of  'note files'  that
                 are  open for the  current job.   Up to 10  note files
                 may  be open for  each job.  The  count is passed back
                 in the  first 3 bytes  of the NERTNC  field.  See  the
                 later discussion on closing the 'note files'.

                 CLO1.   Closes the file named in  the NEFILE parameter
                 for   the   current  job.     If   the   operation  is
                 successful, the  NERTNC field  will be  set to  CLOSED
                 on return.

                 CLOALL.    Closes all  the  note  files open  for  the
                 current  job.   If  the operation  is  successful, the
                 NERTNC field will be set to  CLOSED on return.  If  no
                 files are open, the return value will be NONECLSD.

   NEHTXT        The  heading text  that  appears on  the  top line  of
                 each  note.   You would  normally  want to  place some
                 value  that describes  the unique  key.   For example,
                 it could  be  the customer  number or  customer  name.
                 Up  to 30  bytes may  be entered.   It  is up  to your
                 application program to ensure consistency.

   NERTNC        The  return code that  is passed back  from the 'notes
                 processing' program.   The discussion  of each  NEACTN
                 value describes the return information.

                 A general  error BADSEQ2 will  occur if the  note that
                 is  read  does  not  begin  with  an internal  heading
                 record.   You  should  run the  MTNNTEFIL  command  if
                 this occurs which will clean up the condition.

                 If a  data base error  occurs and  the action code  is
                 not  DSP, the return  value will  be the  exception ID
                 (e.g.  CPF5026 for duplicate key error).

   NELNxx        The  line  information (14  75 byte  fields).   If the
                 ADD or ADDM action  codes are used, the data  is taken
                 from the line  fields and used to add a  note.  If the
                 action  is RTV, the  field values are  filled from the
                 first note  found (it  could be  a Master  note).   If
                 the action  is DSP, the  field values are  filled with
                 the last  note the user displayed,  updated, or added.
                 In  most  applications,  your  program  will  probably
                 choose to ignore the  data for an action code  of DSP.

Opening and closing the note files
----------------------------------

On  each call to  the 'note processing'  program, the file  and library
of  the  'note  file' is  passed  in  the data  structure.    The 'note
processing' program  determines  if the  file is  already  open to  the
current job.  If  not, it opens the file unless the  maximum of 10 open
files already exists for the job.

The  first member  of  each file  is used  (there is  no support  for a
multiple member file).

For most action  codes, the program  returns with LR  off.  The  intent
is  that the  'notes  processing' program  remain  open  and the  'note
files'  that are used regularly  remain open.  This  adds some overhead
to the PAG,  but provides better  performance than continually  opening
and closing the file.

When  your application  is  ready  to close  the  file, there  are  two
typical approaches to take:

  **   Close only  the file associated  with the application.   Specify
       the  NEACTN field as CLO1 and  use the existing NEFILE and NELIB
       values.  This closes  the file, but does not close  the program.
       Any other files  that were open would remain open.   When a file
       is  closed, it no longer  counts toward the maximum  of 10 files
       open.

  **   Close all of  the files and the  program.  It  is safe to  close
       all of  the files and  the program when  there is only  a single
       file  open.   Using  the RTVOPN  action allows  your  program to
       determine how many files are open.

Closing one file or  all files only impacts  the job that performs  the
close.    If the  file  is  closed  and then  re-opened,  the  function
performed is still the same, but performance degrades.

The following  code is in  the correct RPG  format to be  copied into a
program  to allow you  to close the  current file that  you are working
with or all of  the files if there is  only a single file open.   First
use   CPYTAA   TAAARCMBR(NTEFIL)   to   copy  the   source   for   this
documentation member to QATTINFO in TAATOOL.

     C* Close the note file routine
     C                     MOVEL'RTVOPN  'NEACTN           Rtv open
     C                     CALL 'TAANTEAR'                 Process pgm
     C                     PARM           NOTEDS           DS parm
     C* If Return code shows 0 open, branch to end of close
     C*   This can occur if the user requests help and then ends
     C           NERTNC    IFEQ '000'                      0 Open
     C                     GOTO ENDCLS                     End of close
     C                     ENDIF                           0 Open
     C* If Return code shows more than 1 open, close the current file
     C           NERTNC    IFNE '001'                      More than 1
     C                     MOVEL'CLO1    'NEACTN           Close 1
     C                     ENDIF                           More than 1
     C* If Return code shows only 1 open, close all and end TAANTEAR
     C           NERTNC    IFEQ '001'                      1 Open
     C                     MOVEL'CLOALL  'NEACTN           Rtv open
     C                     ENDIF                           1 Open
     C* Close 1 or all
     C                     CALL 'TAANTEAR'                 Process pgm
     C                     PARM           NOTEDS           DS parm
     C           ENDCLS    TAG                             End close

CRTNTEFIL Command parameters                          *CMD
----------------------------

The Create  Note File command is used to create  a note file to be used
by the processing program.

   NTEFIL        The qualified file  name of  the file  to be  created.
                 The library  value defaults  to *CURLIB.   The  member
                 name will be the name of the file.

                 The  file  should  be  created  in  your library  (not
                 TAATOOL) and backed up regularly.

MTNNTEFIL Command parameters                          *CMD
----------------------------

The Maintain  Note File  command  provides for  deletion of  old  notes
(older than a  specified date).  It also  performs a check on  the data
for  internal consistency  and will  delete  any internal  damage (e.g.
notes that do not begin with an internal heading record).

Deletion  of old notes occurs  by writing only the  notes that are more
current than  the date specified  to the TAANTEAT  file in TAATOOL  and
then copying  the net file back  to the file specified  on the command.
The  file  is locked  to ensure  only  a single  job  can be  using the
function at a  time and  that the  file is not  already in  use by  the
'note processing' program.

To provide  for recovery/restart,  the TAANTEFIL  data area in  TAATOOL
is  used.   If  the  command  is interrupted,  you  should  be able  to
recover properly by re-running the command.

   NTEFIL        The  qualified   file  name   of   the  file   to   be
                 maintained.    It  must have  been  created  with  the
                 CRTNTEFIL  command.   The  library  value defaults  to
                 *LIBL.   *CURLIB may  be specified.   The first member
                 of the file is maintained.

   RETENDATE     The retention date  for notes.   It must be  specified
                 in  the format  CYYMMDD.   Any  notes  older than  the
                 date  specified  will be  deleted.   Master  notes are
                 never deleted.

DMONTEFIL Command                                     *CMD
-----------------

The Demonstrate  Note  File command  provides  a demonstration  of  the
Note File tool.   No parameters exist.  The file used  in DMONTEP.  You
can  re-initialize the file with  a few demonstration notes  by doing a
call to TAANTEAC4.

Records in the 'Note file'
--------------------------

The key structure to the file is:

        Your unique key      30 bytes
        Date of the note      7 digits packed(CYYMMDD)
        Seq during the day    1 digit packed (1 - 9)
        Seq within the note   2 digits packed (000- 014)

The value 'Your unique key' should  be a value like customer number  or
library/file/member.

The date assigned for a Master note is 9999999.

The 'Seq during the  day' is automatically assigned as 1  for the first
note  added for  a  unique date.   Additional  notes  are automatically
assigned a number up to 9 for the same date.

The  'Seq  within the  note' field  has a  value of  0 for  the heading
record.   Each note  has a  heading record  which contains  information
about  when  the note  was  last  updated and  the  user  who made  the
change.

Each  line record is assigned a  value of 1 - 14  depending on how many
lines were required.

The last  non-blank line  determines how  many records  are written  to
the data base.  If  the note has data on Line 1  and Line 2, there will
be  three data  base records that  make up  the note (the  heading, and
two detail records.

If the  user enters  data into  Line 1  and Line  3 and  leaves Line  2
blank, the note will  contain 4 data base records (a  heading and three
detail records).

Each  data  base record  contains  the key  of  37 bytes  (some  of the
fields are packed) and a detail portion of 75 bytes.

Data Base conflicts
-------------------

Protection  is provided for  the typical data  base conflict situations
such as:

    - Two users try to update the same record at the same time
    - Two users try to add a new note for the same unique
         key at the same time
    - A user attempts to update a note that another user
         has just deleted

For most conflict situations,  special displays are used to  inform the
user.   In most cases the  user is returned to  the application program
and told to try the operation again.

If  the action code  is not DSP, the  return code will  be set with the
exception ID (e.g.  CPF5026 for duplicate key error).

Rollup/Rolldown
---------------

The Rollup/Rolldown keys will  be active if  there are other notes  for
the same unique key available to be displayed by the user.

An exception to  this occurs when one  user is reviewing the  notes for
a  unique  key and  a  different user  adds  a note.    To  improve the
performance of displaying  notes, the  new note will  not be  available
to be  seen unless the  user returns from  the program and  requests to
display the same unique key.

Restrictions
------------

See the previous section on limits and Rollup/Rolldown.

Prerequisites
-------------

The following TAA Tools must be on your system:

     CHKACTOBJ    Check active object
     CHKACTPGM    Check active program
     EDTVAR       Edit variable
     SNDCOMPMSG   Send completion message
     SNDESCMSG    Send escape message
     SNDSTSMSG    Send status message

Implementation
--------------

See  the previous  discussions  on how  to call  the  'note processing'
program  and  how  to fill  the  data  structure that  is  passed  as a
parameter.

You must  create  a note  file  with CRTNTEFIL  before  a file  can  be
processed by the 'note processing' program.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   CRTNTEFIL     *CMD                   TAANTEA       QATTCMD
   DMONTEFIL     *CMD                   TAANTEA2      QATTCMD
   MTNNTEFIL     *CMD                   TAANTEA3      QATTCMD
   TAANTEAC      *PGM       CLP         TAANTEAC      QATTCL
   TAANTEAC2     *PGM       CLP         TAANTEAC2     QATTCL
   TAANTEAC3     *PGM       CLP         TAANTEAC3     QATTCL
   TAANTEAC4     *PGM       CLP         TAANTEAC4     QATTCL
   TAANTEAC9     *PGM       CLP         TAANTEAC9     QATTCL
   TAANTEAC23    *PGM       CLP         TAANTEAC23    QATTCL
   TAANTEAR      *PGM       RPG         TAANTEAR      QATTRPG
   TAANTEAR2     *PGM       RPG         TAANTEAR2     QATTRPG
   TAANTEAR3     *PGM       RPG         TAANTEAR3     QATTRPG
   TAANTEAR4     *PGM       RPG         TAANTEAR4     QATTRPG
   TAANTEAD      *FILE      DSPF        TAANTEAD      QATTDDS
   TAANTEAE      *FILE      DSPF        TAANTEAE      QATTDDS
   TAANTEAP      *FILE      PF          TAANTEAP      QATTDDS
   TAANTEAT      *FILE      PF
   TAANTEAX      *FILE      PF          TAANTEAX      QATTDDS
   TAANTEFIL     *DTAARA

TAANTEAT is created from TAANTEAP.

Structure
---------

Note processing program

   TAANTEAR   RPG pgm
         TAANTEAX  Externally described data structure
     TAANTEAC9  CL program
     TAANTEAE   Display file

CRTNTEFIL   Cmd
   TAANTEAC    CL pgm
     TAANTEAP     Physical file DDS

DMONTEFIL   Cmd
   TAANTEAC2   CL pgm
     TAANTEAR2   RPG Pgm
       TAANTEAD    Display file

MTNNTEFIL   Cmd
   TAANTEAC3   CL pgm
     TAANTEAC23   CL pgm
        TAANTEAR3   RPG pgm

Initialize DMONTEP file with standard notes for the demonstration

   TAANTEAC4  CL  pgm
     TAANTEAR4   RPG pgm
					

Added to TAA Productivity tools May 1, 1996


Home Page Up to Top