The General Data Base File tool provides a simple ready to use data
base application with standard fields. The tool is intended for
applications where a simple internal data base file is needed for the
application and actions must occur from a CL Program. The tool is
designed for low use activity.
The use of the tool is up to your own imagination. See the later
section for a demonstration of the capability.
The following commands are provided:
ADDGNLDBF Adds a record
RMVGNLDBF Removes a record
UPDGNLDBF Updates a record
RTVGNLDBF Retrieves a record
While these 4 commands are intended to be used in CL programs, only
RTVGNLDBF is restricted to be used in a program.
The data base record that is standard for the tool has the following
fields:
3 Key fields (10 bytes each)
5 Character fields (10 bytes each)
3 Decimal fields (9/0 digits each)
2 Text fields (50 bytes each)
2 Date fields (7 bytes in the CYMD format)
1 Last date change field (display or retrieve only)
1 Last time change field (display or retrieve only)
The file is defined as having a unique key. Not all of the key
fields need to be used, but the combination of the key fields must be
unique.
For ADD, UPD, and RTV, all of the update fields supported by the tool
are available on the command interface. The RTV command also
supports a retrieval of the last change date/time fields which are
automatically updated by the ADD and UPD functions.
The owner of the application has other commands:
CRTGNLDBF Creates the files used by the tool
EDTGNLDBF Subfile of the data with normal options
DLTGNLDBF Deletes the files used by the tool
The intent of the EDT command is to allow the owner of the
application to be able to review or fix the file if problems occur.
Only the owner or a user with *ALLOBJ authority can use EDTGNLDBF.
While the intent of the application is to allow the ADD, RMV, and UPD
commands to run from a CL program, it is possible to authorize the
files for *PUBLIC *USE. and allow the *PUBLIC to use the RTV
command. In this case, the owner of the file would enter all of the
data with either the ADD or EDT command. The *PUBLIC could use the
RTV command.
A demonstration command (DMOGNLDBF) is also available (see the later
section).
You can use the tool for multiple applications, but each set of files
must be in a unique library.
Getting started
---------------
The best solution would be to first run the demonstration described
in a later section. After you are familiar with the basic functions
and have reviewed the code in the demonstration program, you should
be ready to proceed.
1. Select a library where the files used by GNLDBF will exist.
An existing library would normally be used. You may use the
GNLDBF files for multiple applications, but the files must be
unique in a library.
Select a library for the application and also one that you
back up regularly. In these steps, it is assumed that the
library is on your library list. If this is not the case, the
GNLDBFPLIB parameter must be specified on each command.
2. Use CRTGNLDBF to create the required files.
CRTGNLDBF GNLDBFPLIB(xxx) TEXT('...')
The two files created are:
GNLDBFP Physical file
GNLDBFL Logical file with access by arrival sequence
3. The files are created with *PUBLIC allowed *CHANGE authority.
If this does not meet your requirements, use EDTOBJAUT on the
physical file.
4. Use EDTGNLDBF to review the file:
EDTGNLDBF
5. Determine what fields are needed in your application use of
GNLDBF. You can review all of the fields by using F6 to
prompt for a new record.
You must at least use the 'Key 1' field. All other fields are
optional. Determine which fields will be assigned values. It
would be normal to not use all of the fields.
6. If you want to test your application use of GNLDBF, you can
enter some test data using the Add record prompt or use the
ADDGNLDBF command.
7. You may have similar requirements to that shown in the
demonstration program to add a record, retrieve a record,
check or use values, and remove a record. Use the ADD, RTV,
RMV commands as shown in the demonstration program and also
the UPD command if needed.
8. Messages you may want to monitor for are:
TAA9892 A record with the same key already exists
TAA9893 No record exists for the specified key
TAA9895 Not authorized
Demonstration
-------------
Assume you have an application where the users add members to a
certain file, but should only be allowed to remove the members they
have added. The system only tracks ownership at a file level. If
the user is authorized to add a member to the file, he can also
remove any member. Therefore, the application must provide its own
level of security for this function.
What is needed is a small file where each record would have a key of
the member name and a data field that contains the name of the user
who added the member.
To begin the demonstration, you must create a file (TSTMULTMBR) in a
library on your library list that will allow multiple members and
specify AUT(*ALL) to allow other users to be able to add members:
CRTPF FILE(xxxxx/TSTMULTMBR) RCDLEN(10) MAXMBRS(25) +
AUT(*ALL)
Use CRTGNLDBF to create the files needed by the GNLDBF tool in a
library on your library list:
CRTGNLDBF GNLDBFPLIB(xxxxx)
CRTGNLDBF creates two files:
GNLDBFP Physical with unique keys
GNLDBFL Logical in arrival sequence
Do the following steps:
1. Use the demonstration command to add a member:
DMOGNLDBF RQS(*ADD) MBR(MBR1)
The program uses the ADDPFM command to add a member to the
TSTMULTMBR file and the ADDGNLDBF command to add a record to
the GNLDBFP file. A later step will describe how to display
the code.
2. Add a second member:
DMOGNLDBF RQS(*ADD) MBR(MBR2)
3. Because you are the owner of the file, use the EDTGNLDBF
command to review the GNLDBFP file.
EDTGNLDBF
4. You should see the GNLDBFP file displayed with two records.
The 'Key 1' values should be the member names you added. The
other two Key fields are blank (not needed in this
application). The description field is an abbreviated version
of the text description of the user profile that added the
record. This was done by using RTVUSRPRF to access the text
description of the user profile and then specifying it on the
TXT1 parameter of the ADDGNLDBF command.
5. Use Option 5 to display one of the records. You should see
that the 'Character 1' field contains the name of the user
profile who added the record. The last change date and time
are filled in automatically by the ADDGNLDBF command.
The other fields are blank. They could have been entered by
specifying other parameters on ADDGNLDBF.
6. From a different job, signon as a different user profile and
try to add one of the existing members such as:
DMOGNLDBF RQS(*ADD) MBR(MBR2)
You should see the message that the member already exists.
7. Try to remove the member:
DMOGNLDBF RQS(*RMV) MBR(MBR2)
You should see the message that you are not the owner of the
member and therefore cannot remove it. This message is sent
by the application. The term 'owner' represents what the
application considers to be the owner and is not the 'owner'
in terms of i5/OS terminology.
8. Signoff and return to the original job.
9. Remove a member:
DMOGNLDBF RQS(*RMV) MBR(MBR2)
Because you added the member, the code allows you to remove
it.
10. To review the code for the demonstration, use:
DSPTAA TAADBHWC9
The code checks for the files and then handles the ADD or RMV
requests. The ADD, RTV, and RMVGNLDBF commands are used.
11. If you are finished with the demonstration, delete the 3 files
you created:
TSTMULTMBR
GNLDBFP
GNLDBFL
The weakness of the demonstration is that any user who could access
ADDPFM or RMVM could destroy the integrity of the application because
the TSTMULTMBR file must allow the *PUBLIC user to add or remove
members (the user must have *OBJMGT authority to the file to add or
remove a member).
A better solution would be to not allow the *PUBLIC to add or remove
members, but instead use the ADPMBR tool commands of ADDPFMADP and
RMVMADP within the CL program. This would prevent a user operating
from command entry from destroying the integrity of the application.
CRTGNLDBF Command parameters *CMD
----------------------------
GNLDBFPLIB The library where the GNLDBFP and GNLDBFL files
should be created. *CURLIB is the default. The
files must not exist.
TEXT The text description of the files.
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.
EDTGNLDBF Command parameters *CMD
----------------------------
POSKEY1 The first key of the record to 'position to' at the
top of the subfile. A partial key may be entered in
which case a 'set lower limit' type function will
occur. If the field is not used, the first record
in the file is displayed.
POSKEY2 The second key of the record to 'position to' at the
top of the subfile. A partial key may be entered in
which case a 'set lower limit' type function will
occur.
POSKEY3 The third key of the record to 'position to' at the
top of the subfile. A partial key may be entered in
which case a 'set lower limit' type function will
occur.
GNLDBFPLIB The library where the GNLDBFP and GNLDBFL files
exist. *LIBL is the default. *CURLIB may be
specified.
ADDGNLDBF Command parameters *CMD
----------------------------
KEY1 The first key of the record to be added. This is a
required field. The other key fields are optional,
but the value of all 3 key fields must be unique in
the file. Up to 10 bytes may be specified.
KEY2 The second key of the record to be added. The field
is optional. Up to 10 bytes may be specified.
KEY3 The third key of the record to be added. The field
is optional. Up to 10 bytes may be specified.
CHR1 An optional character field. Up to 10 bytes may be
specified.
CHR2 An optional character field. Up to 10 bytes may be
specified.
CHR3 An optional character field. Up to 10 bytes may be
specified.
CHR4 An optional character field. Up to 10 bytes may be
specified.
CHR5 An optional character field. Up to 10 bytes may be
specified.
DEC1 An optional decimal field. The field is defined as
9 digits with 0 decimals. You may use a smaller
size field, but it must have 0 decimals.
DEC2 An optional decimal field. The field is defined as
9 digits with 0 decimals. You may use a smaller
size field, but it must have 0 decimals.
DEC3 An optional decimal field. The field is defined as
9 digits with 0 decimals. You may use a smaller
size field, but it must have 0 decimals.
TXT1 An optional character field. Up to 50 bytes may be
specified. An abbreviated version of the field will
appear on the subfile used by EDTGNLDBF.
TXT2 An optional character field. Up to 50 bytes may be
specified.
DAT1 An optional date field. The date must be entered in
job format and is stored in the record in CYYMMDD
format.
DAT2 An optional date field. The date must be entered in
job format and is stored in the record in CYYMMDD
format.
GNLDBFPLIB The library where the GNLDBFP and GNLDBFL files
exist. *LIBL is the default. *CURLIB may be
specified.
UPDGNLDBF Command parameters *CMD
----------------------------
KEY1 The first key of the record to be updated. This is
a required field. The other key fields are
optional, but the value of all 3 key fields must
specify a record in the file. The TAA9893 message
ID is sent as an escape message if the record does
not exist.
KEY2 The second key of the record to be updated.
KEY3 The third key of the record to be updated.
CHR1 An optional character field. Up to 10 bytes may be
specified. The default is *SAME which means the
current value in the record is not changed.
CHR2 An optional character field. Up to 10 bytes may be
specified. The default is *SAME which means the
current value in the record is not changed.
CHR3 An optional character field. Up to 10 bytes may be
specified. The default is *SAME which means the
current value in the record is not changed.
CHR4 An optional character field. Up to 10 bytes may be
specified. The default is *SAME which means the
current value in the record is not changed.
CHR5 An optional character field. Up to 10 bytes may be
specified. The default is *SAME which means the
current value in the record is not changed.
DEC1 An optional decimal field. The field is defined as
9 digits with 0 decimals. The default is *SAME
which means the current value in the record is not
changed. The value -999999999 may not be used. You
may use a smaller size field, but it must have 0
decimals.
DEC2 An optional decimal field. The field is defined as
9 digits with 0 decimals. The default is *SAME
which means the current value in the record is not
changed. The value -999999999 may not be used. You
may use a smaller size field, but it must have 0
decimals.
DEC3 An optional decimal field. The field is defined as
9 digits with 0 decimals. The default is *SAME
which means the current value in the record is not
changed. The value -999999999 may not be used. You
may use a smaller size field, but it must have 0
decimals.
TXT1 An optional character field. Up to 50 bytes may be
specified. An abbreviated version of the field will
appear on the subfile used by EDTGNLDBF. The
default is *SAME which means the current value in
the record is not changed.
TXT2 An optional character field. Up to 50 bytes may be
specified. The default is *SAME which means the
current value in the record is not changed.
DAT1 An optional date field. The date must be entered in
job format and is stored in the record in CYYMMDD
format. The default is *SAME which means the
current value in the record is not changed.
DAT2 An optional date field. The date must be entered in
job format and is stored in the record in CYYMMDD
format. The default is *SAME which means the
current value in the record is not changed.
GNLDBFPLIB The library where the GNLDBFP and GNLDBFL files
exist. *LIBL is the default. *CURLIB may be
specified.
RMVGNLDBF Command parameters *CMD
----------------------------
KEY1 The first key of the record to be removed. This is
a required field. The other key fields are
optional, but the value of all 3 key fields must
specify a record in the file. The TAA9893 message
ID is sent as an escape message if the record does
not exist.
KEY2 The second key of the record to be removed.
KEY3 The third key of the record to be removed.
GNLDBFPLIB The library where the GNLDBFP and GNLDBFL files
exist. *LIBL is the default. *CURLIB may be
specified.
RTVGNLDBF Command parameters *CMD
----------------------------
KEY1 The first key of the record to be retrieved. This
is a required field. The other key fields are
optional, but the value of all 3 key fields must be
unique in the file. Up to 10 bytes may be
specified. The TAA9893 message ID is sent as an
escape message if the record does not exist.
KEY2 The second key of the record to be retrieved. The
field is optional. Up to 10 bytes may be specified.
KEY3 The third key of the record to be retrieved. The
field is optional. Up to 10 bytes may be specified.
CHR1 An optional character field to be returned. If
specified, the variable must be declared as *CHAR
LEN(10).
CHR2 An optional character field to be returned. If
specified, the variable must be declared as *CHAR
LEN(10).
CHR3 An optional character field to be returned. If
specified, the variable must be declared as *CHAR
LEN(10).
CHR4 An optional character field to be returned. If
specified, the variable must be declared as *CHAR
LEN(10).
CHR5 An optional character field to be returned. If
specified, the variable must be declared as *CHAR
LEN(10).
DEC1 An optional decimal field to be returned. If
specified, the variable must be declared as *DEC
LEN(9 0).
DEC2 An optional decimal field to be returned. If
specified, the variable must be declared as *DEC
LEN(9 0).
DEC3 An optional decimal field to be returned. If
specified, the variable must be declared as *DEC
LEN(9 0).
TXT1 An optional character field to be returned. If
specified, the variable must be declared as *CHAR
LEN(50).
TXT2 An optional character field to be returned. If
specified, the variable must be declared as *CHAR
LEN(50).
DAT1 An optional date field to be returned. If
specified, the variable must be declared as *CHAR
LEN(7) and the date will appear in the format
CYYMMDD.
DAT2 An optional date field to be returned. If
specified, the variable must be declared as *CHAR
LEN(7) and the date will appear in the format
CYYMMDD.
LSTCHGDAT An optional date field to be returned which
represents the last date the record was changed on.
If the record has not been changed, this is the date
the record was added. If specified, the variable
must be declared as *CHAR LEN(7) and the date will
appear in the format CYYMMDD.
LSTCHGTIM An optional time field to be returned which
represents the last time of day the record was
changed. If the record has not been changed, this
is the time the record was added. If specified, the
variable must be declared as *CHAR LEN(7) and the
date will appear in the format CYYMMDD.
GNLDBFPLIB The library where the GNLDBFP and GNLDBFL files
exist. *LIBL is the default. *CURLIB may be
specified.
DLTGNLDBF Command parameters *CMD
----------------------------
GNLDBFPLIB The library where the GNLDBFP and GNLDBFL files
exist. *CURLIB is the default.
DMOGNLDBF Command parameters *CMD
----------------------------
RQS The request type. Either *ADD or *RMV must be
specified.
MBR The member name to add or remove.
Restrictions
------------
None.
Prerequisites
-------------
The following TAA Tools must be on your system:
CHKOBJ2 Check object 2
FILEFDBCK File feedback
HLRMVMSG HLL Remove message
LOCKMSG Lock message
RPGSTSDS RPG Status data structure
RTVDAT Retrieve date
RTVSYSVAL3 Retrieve system value 3
TAAARC TAA Archive
SNDCOMPMSG Send completion message
SNDESCMSG Send escape message
SNDSTSMSG Send status message
WRTSRC Write source
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
CRTGNLDBF *CMD TAADBHW QATTCMD
ADDGNLDBF *CMD TAADBHW2 QATTCMD
RMVGNLDBF *CMD TAADBHW3 QATTCMD
RTVGNLDBF *CMD TAADBHW4 QATTCMD
UPDGNLDBF *CMD TAADBHW5 QATTCMD
EDTGNLDBF *CMD TAADBHW6 QATTCMD
DLTGNLDBF *CMD TAADBHW7 QATTCMD
DMOGNLDBF *CMD TAADBHW9 QATTCMD
TAADBHWC *PGM CLP TAADBHWC QATTCL
TAADBHWC2 *PGM CLP TAADBHWC2 QATTCL
TAADBHWC3 *PGM CLP TAADBHWC3 QATTCL
TAADBHWC4 *PGM CLP TAADBHWC4 QATTCL
TAADBHWC5 *PGM CLP TAADBHWC5 QATTCL
TAADBHWC6 *PGM CLP TAADBHWC6 QATTCL
TAADBHWC7 *PGM CLP TAADBHWC7 QATTCL
TAADBHWC9 *PGM CLP TAADBHWC9 QATTCL
TAADBHWR *PGM RPG TAADBHWR QATTRPG
TAADBHWR4 *PGM RPG TAADBHWR4 QATTRPG
TAADBHWR6 *PGM RPG TAADBHWR6 QATTRPG
TAADBHWD *FILE DSPF TAADBHWD QATTDDS
TAADBHWP *FILE PF TAADBHWP QATTDDS
TAADBHWL *FILE LF TAADBHWL QATTDDS
Structure
---------
CRTGNLDBF Cmd
TAADBHWC CL pgm
ADDGNLDBF Cmd
TAADBHWC2 CL pgm
TAADBHWR RPG pgm
RMVGNLDBF Cmd
TAADBHWC3 CL pgm
TAADBHWR RPG pgm
RTVGNLDBF Cmd
TAADBHWC4 CL pgm
TAADBHWR4 RPG pgm
UPDGNLDBF Cmd
TAADBHWC5 CL pgm
TAADBHWR RPG pgm
EDTGNLDBF Cmd
TAADBHWC6 CL pgm
TAADBHWD Dsp file
TAADBHWR6 RPG pgm
DLTGNLDBF Cmd
TAADBHWC7 CL pgm
DMOGNLDBF Cmd
TAADBHWC9 CL pgm
|
