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
|
