The Name and Address tool is designed to allow you to key in names
and addresses (such as from business cards) and then find a name by
using a simple search technique.
Each user can have his own unique data base or a data base can be
shared by multiple users.
The following features exist:
** Auxiliary keywords can be added. A list of valid keywords can
be entered.
** Search on any value in the name and address or the key fields.
Name and address fields are scanned by default and each word
becomes a key.
** Subfile display shows the records that match the search value.
** Simple display for displaying the data, making changes or
adding new records.
** Options exist such as whether the field should be displayed,
what the prompts are, and what the length and type of the
fields are.
** Scan command to scan for any value in the data base.
** Print command to print all or selected parts of the data base.
** Notes can be added to a name record (done via the NTEFIL
tool).
You can access all the functions from a menu:
GO MENU(NAMADR)
A later section on 'Getting Started' will describe what you need to
do to create the objects required by the NAMADR tool. Before you do
this, you should become familiar with the tool by using the
Demonstration provided.
Basic demonstration
-------------------
The best way to understand the Name and Address tool is to try the
demonstration. Not every supplied function will be used in the
demonstration, but you should get a good idea of the basic functions
and where to look for more detail.
The Demonstration is divided into two sections.
- Basic
- Advanced
The Basic demonstration should give you enough to understand the
concept and a good idea about the general use of the tool.
The Advanced demonstration explores more of the options.
If you are going to being using the NAMADR tool, you will want to go
thru the Advanced section. However, you might want to stop after the
Basic section, create the files as described in the Getting Started
section and then gain some experience by entering some of your own
data.
1. Enter the command:
GO MENU(NAMADR)
2. The NAMADR menu appears with all of the functions. Most of
the options are commands. When you select an option the
command prompt will appear. You can use the Help text
associated with each command to assist you in understanding
the commands and parameters.
Select Option 1 'Edit name and address' and use the Help key
when the command appears. This will give you an idea of the
type of Help text available on each command.
3. Return to the menu. The rest of the demonstration assumes you
will be entering commands from the menu. You could use a
command entry line. The command entry form of the command
will be shown and should be filled in on the Command prompt.
4. Determine a library to be used only for the demonstration.
Note, it is simpler to use a library you do not intend
to use for production data. The last instruction will
suggest you delete the objects with a supplied
command.
5. Select Option 11 for 'Create a demonstration'. A prompt will
appear for the library name. If you are entering commands,
specify:
CALL TAATOOL/TAANAMAC21 PARM(xxxx)
where xxxx is the library you selected.
The program will run the CRTNAMADR command to create the
objects needed, copy demonstration data, and run the RGZNAMADR
command to build the access paths required.
Note, the TAANAMAC21 program uses the required DDS
source in library TAATOOL. If it does not exist, it
uses the source from the TAA Archive. This allows the
demonstration to work with either a full or
demonstration license of the TAA Productivity Tools.
If you use any of the required DDS source from
TAATOOL, all of the DDS source must exist in that
library.
6. Select Option 1 to 'Edit name and address' and enter the
library name you used to create the objects in:
EDTNAMADR NAMADRPLIB(xxxx)
7. The subfile display appears. When no 'Search' value has been
entered on the command, all of the records appear in arrival
sequence and the cursor is positioned on the 'Search on'
field. Use Option 2 (Change) on the Albert Adams record.
8. The Change Record display appears which is the basic entry
display. There are 7 address fields (including the name), 6
telephone fields, 6 auxiliary key fields, and 6 description
fields. These fields are known as ADDR1-7, TEL1-6, AUXKY1-6,
and DESCR1-6 and have standard titles (prompts). The titles
for these fields are highlighted and the text can be changed.
For example, in this demonstration, the text for some of the
Telephone fields has been changed to 'Extension', 'Fax',
'Beeper', and 'Home phone'. You can tailor the text to fit
your needs (a later step will describe how).
The Print ID fields on the bottom of the display work with the
PRTNAMADR command which is described later.
9. The first auxiliary key field has had the text changed to
'Cust/Vend'. Albert Adams has a value of VENDOR.
10. Return to the subfile display. Enter VENDOR into the 'Search
on' field at the top of the display and press Enter.
11. You should see those records that match the value VENDOR. The
cursor is positioned to the first record because a search
value was used. Note that the right hand column indicates
where the match was found and the tailored text for the first
auxiliary key field appears. The 'Bill Thumberbun' record is
not highlighted because the value in the field is VENDORB (use
Option 5 to display the record).
12. The 'Search on' value is used to search against an access path
file that is created from the data. Enter the value TOM into
the 'Search on' field and press Enter. Two records should
appear since the value TOM appears in both the first name and
the last name of two different records. When a record is
added or changed, the name and address data is scanned. Each
word (ended by a blank or a dash) is entered into the access
path file. Some words like 'Mr.' or 'The' are bypassed. You
can control what words are bypassed.
13. Enter the value THUMB into 'Search on' and press Enter. All
of the records that have THUMB will appear. Note that THUMB
may be found in any part of the Name, the company, the
address, the telephone fields, or the auxiliary key fields.
The description fields are not used for keys.
14. You can also search on telephone numbers or Zip codes. Each
piece of a field that is separated by a blank or - (dash)
becomes a separate key value. Enter the value 493 in the
'Search on' field and the records that contain that number or
prefix will appear. Note that the number is used as a
telephone exchange, the beginning part of a specific telephone
number, and the beginning part of a Zip code.
15. Enter the value STOOL in the 'Search on' field and press
Enter. No records will appear because there are no keys that
begin with 'STOOL'. The error message that appears suggests
the use of the F16 key for SCNNAMADR (Scan name and address).
This is a separate command, but can be accessed from the
subfile display.
16. Press F16 and you will see the prompt for the SCNNAMADR
command with the 'Search on' field already specified as the
argument to scan for (you can overkey).
SCNNAMADR will translate every field in the name and address
file including the description fields to upper case and then
scans for the argument. Any data in the additional 'notes'
file is not considered.
Press Enter to scan the file for the word STOOL. A spooled
file will be displayed with the results. The field where the
argument was found is shown along with the first 3 address
fields.
If you want to see the detail record, you must determine which
record you want from the output and then enter a value (such
as the last name) when you return to the subfile display.
17. Return to the subfile display and enter the value TODO
(something 'to do') in the 'Search on' field and press Enter.
Two records should appear. Use option 2 on the 'Phil Beyers'
record. The value TODO appears in the 2nd auxiliary key
field. Assume you have done whatever was needed and now want
to remove the TODO value. Replace the value TODO with the
value DONE and press Enter. You should see an error message
saying that the value is invalid.
Each of the auxiliary key fields can have a unique list of
valid values or multiple auxiliary key fields can share the
same list. In the definition for this application, Auxiliary
key 1 has a unique list and Auxiliary Key 2 and 3 share a
common list.
18. Use F15 to see the list of valid values. From the Auxiliary
Key Valid Values display use F13 to see the keys that are
controlled by the *ALL value.
In this definition, Auxiliary key fields 1-3 have a list of
valid values and 4-6 do not (anything could be keyed into
fields 4-6).
19. Return to the 'Phil Beyers' record and press Enter again. You
should see the same error message.
20. Use F23 for additional information about the message. When
error messages appear and there is additional text, F23 will
be active and you can access more information.
21. Return to the 'Phil Beyers' record and blank out the value
DONE (all blanks in the 2nd Auxiliary Key field). Press
Enter. Since the field is not a 'mandatory entry' in the
demonstration, blanks are valid and the list of valid values
is not checked.
22. Since the TODO value no longer exists in the record, you will
not see the 'Phil Beyers' record on the subfile display. Each
time a record is changed, all of the existing access path
records are deleted for the changed record and then the
existing values are added.
23. Enter the value PHIL in the 'Search on' field, press Enter and
then re-access the Phil Beyers record with the 2 Option.
Change the 2nd Auxiliary key to TODO and press Enter.
24. Then enter TODO in the 'Search on' field and press Enter
again. You should see Phil Beyers back on the TODO list.
Either end the Basic Demonstration at this point or continue with the
Advanced Demonstration.
Advanced demonstration
----------------------
If you are continuing directly from Basic Demonstration, skip to Step
4.
1. The same demonstration data as was created in the Basic
Demonstration can be used for the Advanced Demonstration. If
the data no longer exists, re-create it using the instructions
from the Basic Demonstration.
2. Using either the NAMADR menu or the EDTNAMADR command, access
the subfile display for the demonstration data.
3. Enter PHIL in the 'Search on' field.
4. Access the Phil Beyers record with the 2 Option. Change the
State value from IL to ZZ and press Enter. You should see an
error message because the definition of the application
requires the value be a valid State or Canadian province. Try
entering blanks into the State field and pressing Enter. You
should see a message stating that the field is mandatory and
must be entered.
If you have some addresses that are not in the USA or Canada,
the default definition allows an entry of the State XX. This
allows you to have a mandatory entry State field and still
handle addresses outside the USA and Canada. The Jean Val
Jean record has a State of XX.
Change the State value to IL.
5. Try entering the Zip code field as 1A345. You should see an
error message stating that only numeric values 0-9 are valid.
This is based on the application definition. The default for
most of the fields is that they are character fields and are
not mandatory. For the demonstration, the application
definition was changed so that certain fields could be
validated.
6. Try entering the Zip code field as 123456. You should see an
error message stating that the maximum length is 5. The
default for the Zip code field is that it is a character field
of 12 bytes. The demonstration application definition has
specified a maximum length of 5. You can shorten the length
of most of the fields on the display and control what values
are entered.
7. Enter a Zip code of 60635 for Phil Beyers and press Enter.
8. Re-access the Phil Beyers record with Option 2. Use F7 to
display the Create and Change date information. This
describes who created and changed the record and the date/time
for each. You should see your user profile name as the user
who made the change.
9. Return to the Phil Beyers record and use F9 to access the Note
function. This uses a data base file that is created as part
of the Name and Address objects, but is operated on by the
NTEFIL TAA Tool. It allows you to add notes that relate to
the name and address record. Use F6 to add a note (key in
anything you want). For a full explanation of the NTEFIL
tool, see the NTEFIL documentation.
10. When you return to the Phil Beyers record, you should see an
indication on the top of the display that 'Notes exist'
(assuming you added a record).
11. The Description fields toward the bottom of the Phil Beyers
record can also be used for any notes or additional
descriptive information. The first field has a prompt for
'Internet ID', but the text can be changed.
The Description fields are not used for keys. They are text
only. Press Enter to end the Phil Beyers record.
12. Use the Option 3 (Copy) to copy one of the existing records.
Then use the other options of Change, Display, and Delete to
the new record.
13. When the subfile display appears, use F13 to access the
definition of the application. A menu appears which allows
you to access specific definitions. Enter 1 for the first
option (Headings) and press Enter.
14. The Heading information lets you see what the text is for
several of the prompts that appear on the major displays. F10
may be used to display the same information so that it may be
changed.
Only a user who has *CHANGE authority to the definition can
change the definition. See the later discussion of the
GRT/RVKNAMADR commands.
15. Use F10 to access the change display for the Headings. Change
the title to your own words such as 'My Personal Name and
Address'. This field requires you to right adjust the value.
When you end the change display, you return to the 'Heading
information' again.
16. Press Enter again and you will be back at the subfile display.
Note that the heading of the display has changed.
17. Press F13 to access the definition again and Enter a '1' for
the 'Column Display' The Column display lets you control what
fields and what prompts appear on the subfile display. For
example, the Column 1 field is defined as ADDR1 which is
intended as the name field. You could change this to a
different field and also change the title of the column.
End this display and then return to the subfile display.
When the subfile display appears, note that there is room for
3 fields of 15 characters in length and one field of 8
characters in length. Most of the address fields are 40
characters in length so some truncation occurs on the subfile
display. You cannot change the lengths that appear on the
subfile display.
18. Use F13 to access the Display Definition display. Enter a 1
for the Address fields and press Enter. The Address fields
present a menu for each field with the current text (prompt)
supplied. If you access the definition of ADDR1 you will see
the detail information about the field. Each field has a
series of attributes that control the definition of what is
entered.
Each attribute has Help text that describes the valid entries.
Place the cursor on the 'Allow' field and press Enter. You
should see that there is an option for whether the field is
allowed to appear on the detail record display. For example,
if you are not going to use the ADDR4 field, you could
eliminate it from the display (blanks would appear).
F10 is used for Change mode to change the attributes. Press
F10.
Place the cursor on the 'Type' field and press Help. Roll
through the types of fields that are supported. The default
is C for character.
19. Return to the 'Display Definition' display.
20. The Telephone and Auxiliary Key definitions are similar to the
Address field definitions.
21. The Description field definitions only allow you to change
many of the text descriptions that appear on the display.
22. The Note Tool options allow you to determine what options are
passed to the Note file tool. See the explanation in the
NTEFIL tool documentation.
23. The Print ID options allow you to control whether the fields
appear and their titles.
24. Use F3 to back out to the menu or a command entry line.
25. Select Option 1 to 'Edit name and address' and enter the
command:
EDTNAMADR SEARCH(THUMB) NAMADRPLIB(xxxx)
The SEARCH entry allows you to go right to the records you are
interested in. Return to the menu.
26. Select Option 7 to 'Print Name and Address'. Specify the
library and take all of the other defaults:
PRTNAMADR NAMADRPLIB(xxxx)
If you are on the NAMADR menu, back out to a command entry
line and use WRKSPLF to display the output.
The default output prints all of the information in your Name
and Address file to allow an offline hard copy form. Several
options are provided to tailor the output.
27. Use GO NAMADR again.
Select Option 7 to 'Print Name and Address' again and look at
the prompts. The command works in conjunction with the Print
ID fields that were displayed at the bottom of the detail
record. You do not have to use these fields, but if you want
to tailor the offline hard copy form, see the later discussion
on Printing the Name and Address file. Use F3 to Exit the
Command prompt and return to the menu.
28. When the Name and Address objects are created by the CRTNAMADR
command, the user becomes the owner of the objects and the
*PUBLIC has *USE authority to the objects. This means that
another user could use the files, but could not make any
changes to the data or the definition.
Two commands are provided to assist you with authority. The
GRT/RVKNAMADR commands allow you to grant or revoke authority
to the Name and Address objects.
Select Option 5 for 'Grant name and address objects.' You will
notice that there is an authorization for the data and the
definition. For example, you may want to allow other users to
change your Name and Address files, but not change the
definition. Use F3 to Exit the Command prompt and return to
the menu.
29. Select Option 4 for 'Reorganize name and address objects.'
This command allows you to reorganize the files. If you add
records to the NAMADRP file using CPYF, the CVTDBFFMT tool, or
your own application, there will not be any access path
entries for the added data. The RGZNAMADR command refreshes
the information. If you are out of synch or suspect damage,
see the later discussion of RGZNAMADR.
30. If you change the definition of the application when data
already exists in the file, some of the current records may
not meet your validation rules. The CHKNAMADR command may be
used to check the current data against the application
definition.
Select Option 9 for 'Check name and address.' Run the command
for your library of demonstration data. You should not see
any errors.
31. Because the Name and Address function may be frequently used
during the day, you may want the files left open and a
shorthand command to use the function rather than EDTNAMADR.
The CRTNAMEDT command is designed to create your personal
shorthand command which will provide:
- Access to the function with less keystrokes
- Your own default for the NAMADRPLIB parameter
- Your own default for the SETLR parameter
Select Option 10 for 'Create Shorthand EDT command' Create the
NAM command in a library on your library list and name the
library where your demonstration data exists:
CRTNAMEDT CMD(yyy/NAM) NAMADRPLIB(xxx)
32. Back out to command entry and use the NAM command as:
NAM TOM
You should access the records with TOM as keys.
33. Back out to command entry and duplicate the command and run it
again. You should see a faster response time because the
files are already open.
34. Back out to command entry and close the files with the NAM
command:
NAM SETLR(*ONIMMED)
35. You have finished the demonstration. You should now delete
the objects.
Use the WRKOBJ command to find the NAM command as:
WRKOBJ NAM
Delete the command. When you have created your own personal
name and address objects, you can use CRTNAMEDT to create a
specific command that defaults to the library where your
objects exist.
To delete the demonstration objects in your library, enter:
DLTNAMADR NAMADRPLIB(xxx)
Getting Started
---------------
To begin processing, you must create the objects needed for the Name
and Address tool. You can operate from the NAMADR menu by entering:
GO MENU(NAMADR)
Select Option 2 for 'Create the name and address objects' and enter
your library:
CRTNAMADR NAMADRPLIB(xxx)
This creates the objects that will contain your data into the named
library.
Select Option 1 for 'Edit name and address' and enter your library:
EDTNAMADR NAMADRPLIB(xxx)
You are now ready to enter name and address records or tailor the
application. You may also want a shorthand command as described in
the next section.
Shorthand command
-----------------
Because the EDTNAMADR command may be used very frequently during the
day and you may want to keep the files open, a shorthand command may
be of value.
For example, instead of continually saying:
EDTNAMADR NAMADRPLIB(xxx) SETLR(*OFF)
a shorthand command can be developed that will allow you to say:
NAM
or whatever shorthand name you want.
Since the first parameter is the search field, you could immediately
access the THUMB records with:
NAM THUMB
To create this command, the CRTNAMEDT command is provided (it is also
on the NAMADR menu). You would specify:
CRTNAMEDT CMD(zzz/xxx) NAMADRPLIB(yyyy) SETLR(*OFF) +
TEXT('My shorthand to EDTNAMADR)
CRTNAMEDT duplicates the EDTNAMADR command to the library you named
and changes the defaults of the NAMADRPLIB and SETLR parameters. The
command CPP is the same as that of the EDTNAMADR command, the same
parameters are available, and the same help text exists.
Commands and menus supported
----------------------------
NAMADR Menu (has all of the following commands)
CRTNAMADR Create name and address objects
DLTNAMADR Delete name and address objects
EDTNAMADR Edit name and address
RGZNAMADR Reorganize name and address
GRTNAMADR Grant name and address objects
RVKNAMADR Revoke name and address objects
PRTNAMADR Print name and address
SCNNAMADR Scan name and address
CHKNAMADR Check name and address
CRTNAMEDT Create name and address EDT cmd (shorthand)
Objects created by CRTNAMADR in your library
--------------------------------------------
NAMADRP *FILE PF Name and address master by Arrvl seq
NAMADRQ *FILE PF Access path keys by Key
NAMADRS *FILE LF Access path keys by RR to NAMADRP
NAMADRV *FILE PF Auxiliary key validation by Key/Value
NAMADRW *FILE LF Auxiliary key validation by Arrvl seq
NAMADRN *FILE PF Notes file
NAMADRB *DTAARA Application definition
The NAMADRP Name and Address Record
-----------------------------------
The Name and Address Record is made up of the following fields:
Intended for Number of Maximum length
------------ -------- --------------
Name and address 5 40
State 1 2
Zip code 1 12
Telephone 6 12
Auxiliary keys 6 12
Description 6 60
Print 1 1 3
Print 2 1 3
Print 3 1 4
* Create user 1 10
* Create date 1 7
* Create time 1 6
* Create time modifier 1 3
* Change user 1 10
* Change date 1 7
* Change time 1 6
The * fields are standard and cannot be modified.
While the application has defaults for the definition, you can define
your own descriptions and shorten the lengths of the optional fields,
make some mandatory, etc.
Any 'notes' that are added are placed in a separate data base file
and managed by the NTEFIL tool.
It is up to your own imagination as to how you want to use the
fields. For example, you could decide that a key value of 'TODO'
(something 'to do') will be entered when you have some function to be
performed relating to the Name and address (such as send out some
material). You could then specify a search for the TODO values and
see the work to be done. When the work is completed, you could blank
the TODO value or change the key to the date you performed the work.
Tailoring the application
-------------------------
There are several functions you can perform to tailor the
application. This includes:
** Determining what fields exist on the main displays.
** Changing the prompts that appear for field descriptions and
the title of the display.
** Describing the attributes of each field such as making a
'mandatory entry' field.
** Describing the valid values that may be entered into the Key
fields.
To tailor the application, use F13 from the subfile display.
The prompts and help text will assist you in modifying the
application. See also the later section on Modification. The
following are the major objects used for tailoring:
** The data area NAMADRB is created by CRTNAMADR and will contain
definition defaults. The fields default to 'character' types
and allow any data or blanks to be entered.
** The validity checking fields are stored in the TAANAMAV file
which is created by CRTNAMADR. The default is that any value
may be entered into a Key field without any validity checking.
** A list of values to be bypassed instead of making Access Path
records is defined for names and addresses. For example, it
would be normal to exclude the word 'The'. The words to be
bypassed are kept in the TAANAMAA data area in TAATOOL and act
as a system default. The words could be entered in a language
other than English. You should not modify the TAATOOL
version. See the later discussion for how to tailor the list
of words to be bypassed.
It would be considered normal to change the definition after working
with the Name and Address tool for awhile. You may then have a good
idea of such things as what valid values you want to check for, what
fields should be 'mandatory entry', or the type of fields to specify.
When you change the definition, you may have data in the file that no
longer meets your requirements. To find these errors, the CHKNAMADR
command exists. It reads every record and performs any validity
checking rules on each field.
Search Technique
----------------
The Name and Address file (NAMADRP) defaults so that the records are
entered without any unique key being assigned (you could assign one
of the Auxiliary Key fields as a unique number). The tool uses the
relative record number from the Name and Address record as the key to
a second physical file (NAMADRQ) where the search values are kept.
This is called the Access Path file.
When a record is added to the Name and Address file, the non-blank
values from the fields (except for the Description fields) are
written as separate records to the Access Path file. For a name
field with a value of 'Tom Thumb', the field would be scanned and by
default two records would be entered into the Access Path file (one
for 'Tom' and one for 'Thumb'). This allows you to specify either
value as a search criteria. All the address fields (except State)
and all the Telephone fields default to multiple keys. Each piece of
a telephone number (separated by a blank or dash) becomes a separate
key. Thus if you have a part of a phone number, you can probably
determine who it belongs to in the file.
When a change occurs, all of the existing records with the same
relative record number are deleted and the current values from the
name and address record are used to generate new access path file
records.
When the EDTNAMADR subfile display appears, the rightmost column
describes which field in the record matches the search criteria. For
example, if a match is found on an Auxiliary Key field, the data that
caused the match is probably not on the subfile display. The value
that displays is the field description such as 'Name', but the
description can be tailored. If the value is equal, the field
description appears highlighted. If the value in the record matches
generically, the field description is displayed without highlighting.
When a field is specified as having multiple keys (such as a name
field), any periods, commas, or single character fields are ignored.
Before writing to the Access Path file, the value is checked against
a table to determine if it is a word to be bypassed. For example,
'Inc' or 'The' can be bypassed.
A list of words to be bypassed is standard and can be modified. See
the later section. All keys are translated to upper case when
written to the Access Path file.
The support prevents the same record from appearing more than once in
a subfile (up to 999 entries) if the search value is found in
multiple fields of a Name and Address record. For example, if you
have a record for 'William Williams' and scan for WILLIAM, only one
record would appear in the first 999 entries for WILLIAM.
If you cannot locate a record using the 'Search on' value, the
SCNNAMADR command can be helpful. It will scan the data fields for
the data you are looking for. The fixed fields (such as create date,
Print ID) are not scanned nor is the note file.
Printing the Name and Address file
----------------------------------
The purpose of the PRTNAMADR command is to allow you to make hard
copy versions of your names and addresses. The command has various
options which can be used to select and sort the data before
printing. You may prefer your own format in which case you will need
to write a program to process the NAMADRP file (it is externally
described).
The PRTNAMADR command uses the 'Print ID' fields which exist at the
bottom of the detail record display to assist in selection and
sorting. The fields are flexible enough to allow a variety of
approaches.
** The data is always sorted in order of PRINT1 (high order),
PRINT2, and PRINT3 before printing occurs.
** If the PRINTn fields are used on the PRTNAMADR command,
selection will occur. Records which do not have the
corresponding PRINTn values, will not be printed.
You may want a complete listing of all the names and addresses or you
may want a shorter version of just important names and addresses.
For example, assume you decide that the major print field PRINT1 is
to be used for the letter of the alphabet where you want the name and
address to print. If the name of the person is 'Bill Thumb' who
works for the 'The ABC Company', you probably want to assign either
the letter T for Thumb or A for ABC. Or your may want a numerical
designation such as 030.
The PRINT2 field could be used to provide some relative importance
about the name and address. For example, you may want to use 010 as
a name that is very important to you and 999 for a name that is in
the data base, but you will probably have no contact with again.
If you want to print all names and addresses with an importance of
050 or better, you would specify:
PRTNAMADR PRINT2(050) SEL2(*LE) ...
If you prefer to say 999 is for the most important addresses and want
to print at level 700 or better, you would specify:
PRTNAMADR PRINT2(700) SEL2(*GE) ...
The PRINT3 field could be used to control the sequence within the
other two fields. If you have designated values for PRINT1 and
PRINT2, you might use PRINT3 to control the sequence within.
If you do not have any Print ID values, the data is printed in
arrival sequence.
The PRTNAMADR field will always print the ADDRn fields. The other
fields such as TELn, AUXKYn, or DESCRn are optional. Each optional
field has a corresponding parameter on the PRTNAMADR command. By
default, they print if a value exists in the record.
If you are using the PRINTn fields, you may want to skip to a new
page when a break occurs. For example, if PRINT1 is used for the
letter of the alphabet where you want the name printed, you could
specify that a new page be started with each letter by:
PRTNAMADR SKIP(*PRINT1) ...
The spooled output has a format that is intended for 8 1/2 by 11 inch
pages.
To check all of the records to ensure that they have a Print ID, use
the CHKNAMADR command. It supports parameters to allow you to flag
any records that have blank values.
Copying data to the Name and Address file
-----------------------------------------
It is valid to have a program, CPYF, or the TAA Tool CVTDBFFMT to add
records to the Name and Address file. If you write a program, the
file NAMADRP is externally described for your use.
The From file can be another NAMADRP file or one of your own data
bases. The CVTDBFFMT tool can be helpful if converting from one of
your own data bases.
Unless you use CPYF from another NAMADRP file, you should not attempt
to place any values in the following fields:
NMCRTD Create date
NMCRTT Create time
NMCRTU Create user
NMCRTV Create unique value
NNCHGD Change date
NMCHGT Change time
NMCHGU Change user
After adding records to the file, you must run the RGZNAMADR command
described in the next section. It will assume values for the
previously mentioned fields and create the proper access path
records.
If you copy data from another NAMADRP file, you will lose any Notes
that are part of the From file.
Reorganizing the Files
----------------------
Use of the RGZNAMADR command periodically or for special situations
is recommended.
Because the Relative Record number of the Name and Address file is
used as the key to the Access Path file, there are several functions
that could be performed which would invalidate the data in the Access
Path file. For example, you could use RGZPFM on the Name and Address
file and cause the Relative Record numbers to change. Or if you add
records with a program or CPYF to the Name and Address file, the
Access Path file would not be updated with the new information.
If you change the definition of the application relating to the
Access Path considerations you may also need RGZNAMADR. For example,
if you changed a definition of a telephone field from a 'multiple
key' type to a 'single key' type, the existing data in the Access
Path file is not consistent with your definition and needs to be
rebuilt.
Most changes to the definition such as defining a field as mandatory
are not a consideration for the existing access path keys and you
would not need RGZNAMADR.
The RGZNAMADR command does the following:
** Uses the system RGZPFM command to reorganize the Name and
Address file. This removes any deleted records. If deleted
records existed, the Relative Record numbers of the file have
then changed.
** Rebuilds the Access Path file based on the new Relative Record
numbers and your application definition. The Access Path file
is cleared and then each record is processed as if it were a
new record being added. This will regenerate any key records.
** Ensures that the internal unique key that is generated is
really unique. There is a remote possibility that this will
occur. It is more likely if you use CPYF to copy from another
NAMADRP file. If duplicates are found, instructions are
provided about how to fix the problem.
** Processes the Note File and removes any records for Name and
Address records that no longer exist. When a Delete occurs
from the EDTNAMADR display, no check occurs to delete any
notes related to the name and address record.
** Reorganizes the Note file if any deleted records exist.
Thus anytime the Access Path file no longer matches the Name and
Address file or the Access Path definition of the application
changes, RGZNAMADR rebuilds the structure correctly.
Handling of the Note File
-------------------------
The Note function is provided by using a call to the program provided
by the NTEFIL tool. This will allow you to add notes to any Name and
Address record. A function key from the Display or Change of a name
and address record will allow access to the Note function.
The file used (NAMADRN) is automatically created by CRTNAMADR in the
library you specified. The key to the file is based on the Create
date/time and an internally assigned value which is part of the Name
and Address record. Thus reorganizing the Name and Address file will
not destroy the link between the two files.
If a record is deleted in the Name and Address file, any existing
notes for the record will still remain in the Note file. These will
be cleaned up by the next use of the RGZNAMADR command.
CRTNAMADR command parameters *CMD
----------------------------
NAMADRPLIB The library to contain the objects required by the
tool.
The library should be one which you backup
regularly.
SRCLIB The source library of the DDS source. *TAAARC is
the default to access the source from the TAA
Archive. A specific library may also be used if you
have first copied the source from the Archive to
your library. QATTDDS must be the source file name.
DLTNAMADR command parameters *CMD
----------------------------
NAMADRPLIB The library containing the Name and Address objects.
EDTNAMADR command parameters *CMD
----------------------------
SEARCH The value to search for. If the value is left
blank, the subfile appears with one page of Name and
Address records. The Search field at the top of the
display can be used to enter a search.
The cursor will be positioned at the Search field if
it is blank. If a value was specified, the cursor
will be positioned at the first record.
NAMADRPLIB The library containing the objects used by the tool.
*LIBL is the default. A library or *CURLIB may be
specified.
SETLR The setting of LR when the RPG Search program ends.
The default is * which means to use the setting from
the last time the program was called if it is still
active. If the program has not been active before,
the * value is treated as if *ON had been specified.
The next time the program is called, the files will
be opened and the description of the application
will be re-accessed.
If * is specified and a previous call to the program
specified *OFF, the program ends as if *OFF had been
specified again.
*OFF may be specified if you intend periodic use of
the tool and want to avoid the overhead of opening
and closing files. The next time you use the
function and want to keep the files open, you should
use the default of *. The disadvantages of *OFF are
that 1) More overhead exists in your PAG, and 2) The
files cannot be saved while the files are open for
update.
*ONIMMED may be specified if you want the program to
end and close the files without performing any
search.
RGZNAMADR command parameters *CMD
----------------------------
NAMADRPLIB The library containing the objects. *LIBL is the
default. A library or *CURLIB may be specified.
GRTNAMADR command parameters *CMD
----------------------------
USER The user to grant authority to for the name and
address objects. A user of the system or *PUBLIC
may be used.
NAMADRPLIB The library where the name and address objects
exist. *LIBL is the default. A library or *CURLIB
may also be specified.
DTAAUT The data authority. The default is *USE which means
the user is able to display any of the data, but not
make any changes.
*CHANGE may be specified to allow the user to change
any of the data.
When CRTNAMADR is used, *PUBLIC is allowed *USE
access to the data. If you want to prevent *PUBLIC
access, use RVKNAMADR.
DFNAUT The authority to the definition of the application.
The default is *USE which means the user is able to
use the definition of the name and address
application, but not make any changes to the
definition.
*CHANGE may be specified to allow the user to change
the definition of the application.
RVKNAMADR command parameters *CMD
----------------------------
USER The user to revoke authority from the name and
address objects. A user of the system or *PUBLIC
may be used.
When CRTNAMADR is used, *PUBLIC is allowed *USE
access to the data. If you want to prevent *PUBLIC
access, specify *PUBLIC.
NAMADRPLIB The library where the name and address objects
exist. *LIBL is the default. A library or *CURLIB
may also be specified.
PRTNAMADR command parameters *CMD
----------------------------
PRINT1 The major print ID field. * is the default meaning
all values will be used (the field is not used for
selection criteria).
If a value is entered, it will be used as a
selection criteria. See also the SEL1 parameter.
PRINT2 The intermediate print ID field. This parameter
determines if selection will be used. * is the
default meaning all values will be used (the field
is not used for selection criteria).
If a value is entered, it will be used as a
selection criteria. See also the SEL2 parameter.
PRINT3 The minor print ID field. This parameter determines
if selection will be used. * is the default meaning
all values will be used (the field is not used for
selection criteria).
If a value is entered, it will be used as a
selection criteria. See also the SEL3 parameter.
SEL1 Major print selection.
*EQ is the default meaning only the values specified
for PRINT1 will be used. If PRINT1(*) is used, all
values will be selected.
*LE may be entered to select those values that are
less than or equal to the PRINT1 value. *LE is not
valid if PRINT1(*) is used.
*GE may be entered to select those values that are
greater than or equal to the PRINT1 value. *GE is
not valid if PRINT1(*) is used.
SEL2 Intermediate print selection.
*EQ is the default meaning only the values specified
for PRINT2 will be used. If PRINT2(*) is used, all
values will be selected.
*LE may be entered to select those values that are
less than or equal to the PRINT2 value. *LE is not
valid if PRINT2(*) is used.
*GE may be entered to select those values that are
greater than or equal to the PRINT2 value. *GE is
not valid if PRINT2(*) is used.
SEL3 Minor print selection.
*EQ is the default meaning only the values specified
for PRINT3 will be used. If PRINT3(*) is used, all
values will be selected.
*LE may be entered to select those values that are
less than or equal to the PRINT3 value. *LE is not
valid if PRINT3(*) is used.
*GE may be entered to select those values that are
greater than or equal to the PRINT3 value. *GE is
not valid if PRINT3(*) is used.
SKIP Whether to skip to a new page when one of the PRINTn
fields changes. *NONE is the default and causes
only normal overflow skipping to occur.
*PRINT1 causes a skip to a new page if the value in
the PRINT1 field for a record to be printed has
changed.
*PRINT2 causes a skip to a new page if the value in
the PRINT2 field for a record to be printed has
changed.
*PRINT3 causes a skip to a new page if the value in
the PRINT3 field for a record to be printed has
changed.
NAMADRPLIB The library where the name and address objects
exist. *LIBL is the default. A library or *CURLIB
may be specified.
TEL1 A Y/N value for whether the TEL1 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
TEL2 A Y/N value for whether the TEL2 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
TEL3 A Y/N value for whether the TEL3 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
TEL4 A Y/N value for whether the TEL4 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
TEL5 A Y/N value for whether the TEL5 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
TEL6 A Y/N value for whether the TEL6 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
AUXKY1 A Y/N value for whether the AUXKY1 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
AUXKY2 A Y/N value for whether the AUXKY2 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
AUXKY3 A Y/N value for whether the AUXKY3 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
AUXKY4 A Y/N value for whether the AUXKY4 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
AUXKY5 A Y/N value for whether the AUXKY5 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
AUXKY6 A Y/N value for whether the AUXKY6 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
DESCR1 A Y/N value for whether the DESCR1 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
DESCR2 A Y/N value for whether the DESCR2 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
DESCR3 A Y/N value for whether the DESCR3 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
DESCR4 A Y/N value for whether the DESCR4 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
DESCR5 A Y/N value for whether the DESCR5 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
DESCR6 A Y/N value for whether the DESCR6 field should be
printed. The default is Y for yes which will cause
the field to print if it contains a non-blank value.
SCNNAMADR command parameters *CMD
----------------------------
ARGUMENT The argument to scan for.
NAMADRPLIB The library where the name and address objects
exist. *LIBL is the default. A library or *CURLIB
may be specified.
OUTPUT How to output the results. * is the default.
*PRINT may be specified. This is the same
definition as most DSP commands.
CHKNAMADR command parameters *CMD
----------------------------
NAMADRPLIB The library where the name and address objects
exist. *LIBL is the default. A library or *CURLIB
may be specified.
PRINT1 A *YES/*NO value that defaults to *NO. *NO means
that any value in the PRINT1 field is valid
including blanks.
*YES means to print an error if a blank value is
found.
PRINT2 A *YES/*NO value that defaults to *NO. *NO means
that any value in the PRINT2 field is valid
including blanks.
*YES means to print an error if a blank value is
found.
PRINT3 A *YES/*NO value that defaults to *NO. *NO means
that any value in the PRINT3 field is valid
including blanks.
*YES means to print an error if a blank value is
found.
CRTNAMEDT command parameters *CMD
----------------------------
CMD The qualified name of the command you want to
create. The command name must not already exist in
the specified library. The library defaults to
*CURLIB.
NAMADRPLIB The default library for the NAMADRPLIB parameter.
This should be the library where the name and
address objects exist.
SETLR The default for the SETLR parameter. *OFF is the
default which differs from the EDTNAMADR default.
This will keep the files open to allow a faster
access the next time the command is used.
*, *ON, or *ONIMMED may be used. For a complete
understanding, see the same parameter on the
EDTNAMADR command.
TEXT The text of the command definition object.
Defining the Application
------------------------
A default definition is provided when you use CRTNAMADR. The NAMADRB
data area is created with defaults.
To modify the defaults, use the F13 option from the subfile display.
It provides an interactive interface and help text to assist you.
You must have *CHANGE authority to the definition to be able to
change it. See the GRTNAMADR command.
See the following sections for additional tailoring details.
Auxiliary Key field validity checking
-------------------------------------
Each of the 6 Auxiliary Key fields can have individual validity
checking or any of the fields may use a common set of valid entries.
For example, you could decide that the first 4 Auxiliary Key fields
will be used for characteristics of the Name record such as SUPPLIES,
PAPER, RIBBONS. You define the valid keywords as being for Auxiliary
Key *ALL and then define Auxiliary Key fields 1-4 as using the *ALL
function. You could enter any of the valid keywords into Auxiliary
Keys 1-4. You might decide to use Auxiliary Key 5 to describe the
type of record such as PERSONAL, CUSTOMER, VENDOR, or OTHER. You
could change the definition of Auxiliary Key 5 to specify a list and
then use the Function key to access the display that allows entry of
the values.
You can have some or all Auxiliary Key fields that have no valid
value checking. All of the fields are optional by default meaning
that blank values are valid (not 'mandatory entry').
To see the list of valid values, use F15 from the detail record
display. To change the list, use F13 from the subfile display and
select the option to access the Auxiliary Key field definition.
Select the desired Auxiliary Key field and modify the attribute for
List of Values. Once the field is specified as being checked for
valid values, command key F15 will be active to allow you to access
the valid values and make changes.
State and Province Validation
-----------------------------
The abbreviations for the 50 states, DC, and PR (Puerto Rico) are
contained in the TAANAMAA data area in TAATOOL.
The value XX is supplied as a State and as a Canadian Province. This
value is intended to allow the State field to be used as a mandatory
entry field and still provide for addresses that are outside the US
or Canada.
You can change the definition (such as eliminating the XX State).
See the next section.
Modifying the TAANAMAA Data Area
--------------------------------
The TAANAMAA data area is used to hold words that will be bypassed
(not included in the access path files) and State and Province
abbreviations.
When a name field is entered such as 'The ABC Co.', it is normal to
want to exclude the words 'The' and 'Co.'.
Any blanks, or single character values, commas, or periods are
automatically excluded.
A default list of words to be bypassed is provided in a data area in
TAATOOL. There is a unique set of words for a Name type of field
which will bypass words like 'Mr' or 'The' and another unique set of
words for an Address like 'Ave' or 'St'. You may also define your
own set. The data area in TAATOOL should not be modified as it will
be replaced on the next release (see later discussion for how to
duplicate). You can see the data area by the command:
DSPDTAARA DTAARA(TAATOOL/TAANAMAA)
The layout of the data area is designed to be maintained by the TAA
Tool EDTDTAARA2 command.
The data area is divided into 4 sections. The first 500 bytes are
for words to be bypassed for Name type fields. There is room for 40
words with each word taking up 12 bytes and two extra bytes at the
end of each line. Periods are entered where no word exists (these
are not used in the search, but are designed to assist you in
entering data by keying over the period). Each of the other sections
has a similar layout.
Bytes 501-999 are words to be bypassed in Addresses.
Bytes 1001-1499 are reserved for your own needs as a User defined set
of words that may be unique to your application. The row of entries
begins with defaults of USER, USER... These are intended to be
replaced.
Bytes 1501-1700 contain the USA State abbreviations. You can add or
delete from this list. The XX State is intended to allow the field
be defined as mandatory entry and still allow addresses outside the
USA or Canada to be entered.
Bytes 1701-1800 contain the Canadian Province abbreviations and the
XX entry.
The support allows you to do one of the following:
** Use the default as provided in TAATOOL.
** Define your own installation wide default. The version must
be in QGPL. Do the following:
CRTDUPOBJ OBJ(TAANAMAA) FROMLIB(TAATOOL) +
OBJTYPE(*DTAARA) TOLIB(QGPL) +
NEWOBJ(NAMADRA)
EDTDTAARA2 DTAARA(QGPL/NAMADRA)
And change the words to fit your requirements.
** Define your own application needs by creating the data area in
the library with the name and address objects. Do the
following:
CRTDUPOBJ OBJ(TAANAMAA) FROMLIB(TAATOOL) +
OBJTYPE(*DTAARA) TOLIB(xxx) +
NEWOBJ(NAMADRA)
EDTDTAARA2 DTAARA(xxx/NAMADRA)
And change the words to fit your requirements.
The search technique used to determine which data area to use, is:
** If the data area NAMADRA exists in the same library as the
NAMADRP file, it is used.
** If not in the NAMADRP library, the data area is looked for in
QGPL and if found, it is used.
** If not in either of the above, the default version in TAATOOL
is used.
Restrictions
------------
The number of name and address records that can exist is 999,999,999.
Prerequisites
-------------
The following TAA Tools must be on your system:
CHKACTOBJ Check active object
CHKOBJ2 Check object 2
CPYTAADDS Copy TAA DDS
EDTVAR Edit variable
FILEFDBCK File feedback
HLRMVMSG HLL Remove message
LOCKMSG Lock message
NTEFIL Note file
PMTOPR Prompt operator
RTVSYSVAL3 Retrieve system value 3
SNDCOMPMSG Send completion message
SNDDIAGMSG Send diagnostic message
SNDESCMSG Send escape message
SNDSTSMSG Send status message
WRTSRC Write source
Implementation
--------------
The tool is ready to use, but you must use CRTNAMADR to create the
objects needed.
You will probably want to tailor the definition of the application as
described previously.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
EDTNAMADR *CMD TAANAMA QATTCMD
CRTNAMADR *CMD TAANAMA2 QATTCMD
RGZNAMADR *CMD TAANAMA3 QATTCMD
DLTNAMADR *CMD TAANAMA4 QATTCMD
GRTNAMADR *CMD TAANAMA5 QATTCMD
RVKNAMADR *CMD TAANAMA6 QATTCMD
PRTNAMADR *CMD TAANAMA7 QATTCMD
SCNNAMADR *CMD TAANAMA8 QATTCMD
CRTNAMEDT *CMD TAANAMA9 QATTCMD
CHKNAMADR *CMD TAANAMA10 QATTCMD
TAANAMAC *PGM CLP TAANAMAC QATTCL
TAANAMAC2 *PGM CLP TAANAMAC2 QATTCL
TAANAMAC3 *PGM CLP TAANAMAC3 QATTCL
TAANAMAC4 *PGM CLP TAANAMAC4 QATTCL
TAANAMAC5 *PGM CLP TAANAMAC5 QATTCL
TAANAMAC6 *PGM CLP TAANAMAC6 QATTCL
TAANAMAC7 *PGM CLP TAANAMAC7 QATTCL
TAANAMAC8 *PGM CLP TAANAMAC8 QATTCL
TAANAMAC9 *PGM CLP TAANAMAC9 QATTCL
TAANAMAC10 *PGM CLP TAANAMAC10 QATTCL
TAANAMAC11 *PGM CLP TAANAMAC11 QATTCL
TAANAMAC21 *PGM CLP TAANAMAC21 QATTCL
TAANAMAC22 *PGM CLP TAANAMAC22 QATTCL
TAANAMAC23 *PGM CLP TAANAMAC23 QATTCL
TAANAMAR *PGM RPG TAANAMAR QATTRPG
TAANAMAR3 *PGM RPG TAANAMAR3 QATTRPG
TAANAMAR7 *PGM RPG TAANAMAR7 QATTRPG
TAANAMAR8 *PGM RPG TAANAMAR8 QATTRPG
TAANAMAR10 *PGM RPG TAANAMAR10 QATTRPG
TAANAMAR12 *PGM RPG TAANAMAR12 QATTRPG
TAANAMAR13 *PGM RPG TAANAMAR13 QATTRPG
TAANAMAR14 *PGM RPG TAANAMAR14 QATTRPG
TAANAMAR15 *PGM RPG TAANAMAR15 QATTRPG
TAANAMAD *FILE DSPF TAANAMAD QATTDDS
TAANAMAE *FILE DSPF TAANAMAE QATTDDS
TAANAMAF *FILE DSPF TAANAMAF QATTDDS
TAANAMAG *FILE DSPF TAANAMAG QATTDDS
Objects used by the tool - Continued
------------------------------------
TAANAMAP *FILE PF TAANAMAP QATTDDS
TAANAMAQ *FILE PF TAANAMAQ QATTDDS
TAANAMAS *FILE LF TAANAMAS QATTDDS
TAANAMAV *FILE PF TAANAMAV QATTDDS
TAANAMAW *FILE LF TAANAMAW QATTDDS
TAANAMAZ *FILE PF TAANAMAZ QATTDDS
NAMADR *MENU No source
TAANAMAA *DTAARA No source
TAANAMAB *DTAARA No source
TAANAMAT1 *FILE PF No source
TAANAMAT2 *FILE PF No source
TAANAMAT3 *DTAARA No source
The TAANAMTx objects are used to supply the demonstration data.
The data base file usage is:
TAANAMAP creates NAMADRP - Name and Address PF by Arrvl seq
TAANAMAQ creates NAMADRQ - Access Path PF by Key
TAANAMAS creates NAMADRS - Access Path LF by NAMADRP RR
TAANAMAV creates NAMADRV - Valid values PF by Key/Value
TAANAMAW creates NAMADRW - Valid values LF by Arrvl seq
TAANAMAZ Work file used by RGZNAMADR
The NAMADRN file is created by using the CRTNTEFIL command from the
NTEFIL tool.
Structure
---------
NAMADR Menu
TAANAMAC23 CL Pgm
TAANAMAG Display file
EDTNAMADR Cmd
TAANAMAC CL Pgm
TAANAMAR RPG Pgm
TAANAMAD Display file
TAANAMAC11 CL Pgm - Updates data area
TAANAMAC22 CL Pgm - SCNNAMADR
TAANAMAR14 RPG Pgm - Access valid keys
TAANAMAE Display file
TAANAMAR15 RPG Pgm - Display valid keys
TAANAMAF Display file
CRTNAMADR Cmd
TAANAMAC2 CL pgm
DLTNAMADR Cmd
TAANAMAC4 CL pgm
RGZNAMADR Cmd
TAANAMAC3 CL pgm
TAANAMAR3 RPG Pgm
TAANAMAR12 RPG Pgm - Read work file - ensure unique values
TAANAMAR13 RPG Pgm - Delete unused note file records
GRTNAMADR Cmd
TAANAMAC5 CL pgm
RVKNAMADR Cmd
TAANAMAC6 CL pgm
PRTNAMADR Cmd
TAANAMAC7 CL pgm
TAANAMAR7 RPG Pgm
SCNNAMADR Cmd
TAANAMAC8 CL pgm
TAANAMAR8 RPG Pgm
CHKNAMADR Cmd
TAANAMAC10 CL pgm
TAANAMAR10 RPG Pgm
Structure - Continued
---------------------
CRTNAMEDT Cmd
TAANAMAC9 CL pgm
TAANAMAC21 CL Pgm - Create demonstration
|
