The CLP Data Base Record tool provides a command interface to allow a
CL program to position to (key or RR), read sequentially, read
randomly (by key or RR), write, update, and delete data base records.
A record buffer (string of data) must be provided (the tool does not
operate on a list of fields - see the later discussion of CRTCLPDCL).
The main intent of the CLPDBR tool is to bring full data base
functions to CL programs that require a small amount of data
handling. You should not consider the tool as a replacement for
performance sensitive applications.
The file to be used must be identified ahead of time by entering a
record in a control file for the name of the file/library to be used.
The owner of the control file can control who may enter records
describing the files to be used. See the later section on 'Security
and Integrity'.
To minimize potential errors where the format of a file may change,
the level ID of the specified file is extracted when a record is
written to the control file. This level ID must be the same as the
level ID when the file is opened. If not, an escape message is
issued. You must update the record in the control file to
re-establish the current level ID and review the program code to
ensure that it is still operating on the correct definition. For
example, the from/to positions of the data may have changed.
An exception to the level check requirement exists for *ALLOBJ users.
If the user has *ALLOBJ authority (or the program adopts this
authority), LVLCHK(*NO) may be specified on OPNDBR. This allows an
*ALLOBJ user to use the function with a variable file name.
An exception is also made for certain TAA tool programs which allows
a name of a program to be checked to allow LVLCHK(*NO).
Program described file approach
-------------------------------
Because a buffer is passed to the data base, the function of CLPDBR
operates like any program that has a program described file. It is
possible to write bad data into decimal fields.
This potential problem can be virtually eliminated by:
** The use of the level ID check described previously and
** The use of the TAA CRTCLPDCL tool. CRTCLPDCL will create a
data structure and the sub fields to match the definition of
an externally described file.
Commands provided
-----------------
Menu of commands (use GO CLPDBR)
--------------------------------
CLPDBR - Menu of commands
Controlling file commands
-------------------------
CRTDBRCTL - Creates the control files DBRCTLP and DBRCTLL
WRKDBRCTL - Works with the files to be used by CLPDBR
DLTDBRCTL - Deletes the control files
Processing commands (may only be used in a CL program)
------------------------------------------------------
OPNDBR - Opens the file
RDDBR - Reads a record (Seq or Random)
WRTDBR - Writes a record
UPDDBR - Updates a record
DLTDBR - Deletes a record
POSDBR - Positions to a key or RR number
RLSDBR - Releases a record lock
CLSDBR - Closes the file
Cleanup command (for use when errors occur or cleanup)
------------------------------------------------------
RCLDBR - Reclaims CLPDBR (close all files, pgms)
Getting started
---------------
** A control file must be created before identifying any files to
be used with the CLPDBR tool. Only a user with *ALLOBJ
authority may use CRTDBRCTL.
CRTDBRCTL DBRCTLLIB(xxx)
A physical (DBRCTLP) and logical file (DBRCTLL) are created.
The default for the AUT parameter is *RPGLIKE meaning the
authority to use the CLPDBR functions is similar to the use of
RPG. The *RPGLIKE function allows any user to be able to add
a record to describe a file to be used by the CLPDBR
functions. See the later section on 'Security and Integrity'
and 'Security approaches'.
Multiple sets of control files may be created in different
libraries.
** A file must be identified to be used by the CLPDBR tool.
WRKDBRCTL DBRCTLLIB(xxx)
A work display appears. To identify a file to be used, use F6
and add the files that will be used.
The level ID of the file is stored with the name of the file.
The level ID is checked when the file is opened.
** The file may now be used in a CL program. See the next
section.
Basic programming concepts using the CLPDBR functions
-----------------------------------------------------
The file must be opened by OPNDBR:
OPNDBR FILE(ABC)
Several defaults occur when OPNDBR is specified with just a file
name:
** The library list is used to find the file and determine the
library.
** The member defaults to *FIRST.
** The OPTION parameter defaults to 'input only' meaning the file
cannot be updated or added to.
** The file is opened as it is defined. For example, if it is
keyed, it is ready to be processed in keyed order.
** An OPNID is assigned using the default name TAADFTDBR.
** The DBRCTLP file must be found using the library list.
The DBRCTLP file must contain a record for the ABC file.
A data area in QTEMP is created with the OPNID name (default is
TAADFTDBR). The data area acts as a control block when other CLPDBR
commands are run.
The user must have authority to the file based on how the file is
opened (*USE in this case).
The RDDBR command is used to read a record.
RDDBR RCD(&rcd)
Several defaults occur when RDDBR is specified with just a return
variable for the record buffer.
** The OPNID defaults to TAADFTDBR which is the same as on the
OPNDBR command.
** TYPE(*NEXT) is the default which causes a read to the next
record in the file (or the first record if no record has been
read prior). If OPNDBF SEQOPTION(*FILE) was specified and the
file was keyed, the lowest key value record would be read.
The TAADFTDBR data area would be accessed and checked.
Since the file cursor is positioned at the beginning of the file when
a file is opened, the first record in the file would be read.
The &rcd variable must be declared as *CHAR LEN(5000). This happens
if the CRTCLPDCL command default is used. CRTCLPDCL creates a data
structure and the sub fields which match the definition of the
externally described file. The data structure name defaults to the
format name of the file and is given a length of 5000. The sub
fields may be read and changed such as in any HLL approach. When
reading or writing to the file, the &rcd variable name is used.
If you are not using CRTCLPDCL or some similar technique, it is up to
the program to substring out of the &rcd variable to access the
individual fields.
When you are finished with the file, it must be closed:
CLSDBR
This closes the file to the system and deletes the data area named on
the OPNID parameter (default is TAADFTDBR).
Sample programs using the CLPDBR functions
------------------------------------------
** Read all records in a file
DCL &RCD *CHAR LEN(5000)
.
OPNDBR FILE(xxx)
READ: RDDBR RCD(&RCD)
MONMSG MSGID(TAA9892) EXEC(GOTO EOF)
/*****************************************/
/* */
/* Your processing of the data */
/* in &RCD */
/* */
/*****************************************/
GOTO READ
EOF: RMVMSG MSGTYPE(*EXCP)
CLSDBR
The default for RDDBR is TYPE(*NEXT) which causes the next
record in the file to be read.
Monitoring for TAA9892 is required to check for 'end of file'.
** Add a record to the end of the file
DCL &RCD *CHAR LEN(5000)
.
OPNDBR FILE(xxx) OPNTYPE(*OUT)
/*****************************************/
/* */
/* Build data for record in &RCD */
/* */
/*****************************************/
WRTDBR RCD(&RCD)
CLSDBR
More than one record may be written by coding a loop.
Additions occur at the end of the file. An option exists to
write to a deleted record slot using a relative record number.
An escape message would occur if a duplicate key was attempted
to be written to a file that requires unique keys.
** Randomly access a record with the key of MMMMM and update it
DCL &RCD *CHAR LEN(5000)
.
OPNDBR FILE(xxx) OPNTYPE(*ALL)
RDDBR TYPE(*EQUAL) RCD(&RCD) KEY(MMMMM)
/*****************************************/
/* */
/* Change &RCD variable as needed */
/* */
/*****************************************/
UPDDBR RCD(&RCD)
CLSDBR
An escape message would be issued by RDDBR if the MMMMM record
did not exist.
An escape message would be issued by UPDDBR if the update
caused a duplicate key in a file that requires unique keys.
** Randomly access all records with a key of SSSSS
DCL &RCD *CHAR LEN(5000)
.
OPNDBR FILE(xxx)
POSDBR KEY('SSSSS')
MONMSG MSGID(TAA9892) EXEC(DO) /* No records */
/*****************************************/
/* */
/* Your processing for no records */
/* in existence for the key */
/* */
/*****************************************/
ENDDO /* No records */
READ: RDDBR TYPE(*NEXTEQ) RCD(&RCD)
MONMSG MSGID(TAA9892) EXEC(GOTO ENDGRP)
/*****************************************/
/* */
/* Your processing of each record */
/* */
/*****************************************/
GOTO READ
ENDGRP: RCVMSG MSGTYPE(*EXCP)
CLSDBR
The POSDBR command defaults to position by key. The cursor is
set at the first SSSSS key and establishes the key of that
record for subsequent use of RDDBR TYPE(*NEXTEQ). Note that
if the key does not exist, a MONMSG for TAA9892 is used to
handle the exception.
The RDDBR request of TYPE(*NEXTEQ) reads the next record if it
has the same key. A MONMSG is also used for TAA9892 which
indicates that no more records exist for the same key.
** Randomly access all records with a key of TTTTT and read
backwards thru the group
DCL &RCD *CHAR LEN(5000)
DCL &KEY *CHAR LEN(10)
DCL &KEY2 *CHAR LEN(10)
.
OPNDBR FILE(xxx)
CHGVAR &KEY 'TTTTT'
POSDBR KEYOPTION(*GT) KEY(&KEY)
MONMSG MSGID(TAA9892) EXEC(DO) /* Not found */
GOTO NOTFOUND
ENDDO /* Not found */
RDDBR TYPE(*PREV) RCD(&RCD)
MONMSG MSGID(TAA9892) EXEC(DO) /* No record found */
GOTO NOTFOUND
ENDDO /* No record found */
CHGVAR &KEY2 %SST(&RCD nn 10)
IF (&KEY *NE &KEY2) DO /* Not expected key */
GOTO NOTFOUND
ENDDO /* Not expected key */
/* Expected key was found */
GOTO PROCESS
READ: RDDBR TYPE(*PREVEQ) RCD(&RCD)
MONMSG MSGID(TAA9892) EXEC(DO) /* End of group */
GOTO ENDGRP
ENDDO /* End of group */
/*****************************************/
/* */
PROCESS: /* Your processing of &RCD */
/* */
/*****************************************/
GOTO READ
ENDGRP: RCVMSG MSGTYPE(*EXCP)
CLSDBR
.
/*****************************************/
/* */
NOTFOUND: /* Your coding for the requested */
/* key was not found */
/* */
/*****************************************/
ENDPGM
POSDBR sets the file cursor to the record (if any) following
the key specified. A MONMSG command is used to ensure that at
least one record exists that is greater than the key
specified.
The RDDBR of TYPE(*PREV) reads the last record of the group.
A comparison is made to ensure that it is the correct group.
If it is the desired record, a branch to the processing
portion of the code occurs.
The RDDBR command in the main loop uses TYPE(*PREVEQ) and
monitors for 'not found' which could either be the last record
of a group or the beginning of the file.
Partial keys
------------
The POSDBR command requires an exact key if *EQ is specified.
If an option like *GE is specified, the number of characters in the
key may be less than the full key. For example, if the key is 5
bytes in length, you may pass a key of MM and specify *GE. The
cursor would be positioned to the first MM or greater record.
The RDDBR command with TYPE(*EQUAL) also requires an exact key.
Multiple files or opening the same file multiple times
------------------------------------------------------
You can process multiple files (including the same file) in the same
CL program (overall limit of 2000 files).
The commands default the OPNID parameter to TAADFTDBR. If you have a
second file to be open at the same time, you must specify a unique
OPNID on OPNDBR and any commands that process the file (such as
RDDBR).
For example, you may have code that looks like:
DCL &RCD *CHAR LEN(5000)
DCL &RCD2 *CHAR LEN(5000)
.
OPNDBR FILE(ABC)
OPNDBR FILE(DEF) OPNID(DEF)
RDDBR RCD(&RCD)
RDDBR RCD(&RCD2) OPNID(DEF)
.
CLSDBR
CLSDBR OPNID(DEF)
If you close the ABC file (default OPNID of TAADFTDBR), you may open
another file using the default OPNID. If more than one file is to be
open at the same time, you must use the OPNID parameter for all
actions on any additional files.
Use of CRTCLPDCL
----------------
The CRTCLPDCL command provides an automatic create of a data
structure and the individual fields that make up an externally
described data structure.
The command is run after you have added the source member to a file
that you want the DCLs generated into.
For example, assume you have an externally described data base file
named TEST1PF that you want to update with CLPDBR. Assume the file
definition is:
A R RCD1
A FIELDA 5
A FIELDB 3 0
A FIELDC 20
A K FIELDA
Assume your CLP source member is named UPDTEST1PF. After adding the
UPDTEST1PF member to the file, you would enter the CRTCLPDCL command
as:
CRTCLPDCL FILE(TEST1PF) SRCFILE(QCLSRC)
SRCMBR(UPDTEST1PF)
When the command completes, the following statements would be added
to the end of member UPDTEST1PF:
/* Defined from TEST1PF in SLOANT */
/* Start CRTCLPDCL definitions - 02/15/09 */
DCL VAR(&RCD1) TYPE(*CHAR) LEN(5000)
DCL VAR(&FIELDA) TYPE(*CHAR) LEN(5) STG(*DEFINED) +
DEFVAR(&RCD1 1)
DCL VAR(&FIELDB) TYPE(*DEC) LEN(3 0) STG(*DEFINED) +
DEFVAR(&RCD1 6)
DCL VAR(&FIELDC) TYPE(*CHAR) LEN(20) STG(*DEFINED) +
DEFVAR(&RCD1 8)
/* End of CRTCLPDCL definitions */
CRTCLPDCL is designed to work with CLPDBR. Note that the &RCD1
variable is declared as 5000 bytes which is required by CLPDBR. The
fields within the file have been defined as subfields within &RCD1 by
use of the STG and DEFVAR parameters.
You need to use a source editor to move the generated statements to
the proper place in the program.
Assume you will pass the key of a record you want to access into the
program, retrieve the record, add one to FIELDB, and update the
record.
PGM PARM(&KEY)
DCL VAR(&KEY) TYPE(*CHAR) LEN(5)
/* Defined from TEST1PF in SLOANT */
/* Start CRTCLPDCL definitions - 02/15/09 */
DCL VAR(&RCD1) TYPE(*CHAR) LEN(5000)
DCL VAR(&FIELDA) TYPE(*CHAR) LEN(5) STG(*DEFINED) +
DEFVAR(&RCD1 1)
DCL VAR(&FIELDB) TYPE(*DEC) LEN(3 0) STG(*DEFINED) +
DEFVAR(&RCD1 6)
DCL VAR(&FIELDC) TYPE(*CHAR) LEN(20) STG(*DEFINED) +
DEFVAR(&RCD1 8)
/* End of CRTCLPDCL definitions */
OPNDBR FILE(TEST1PF) OPNTYPE(*ALL)
RDDBR TYPE(*EQUAL) RCD(&RCD1) KEY(&KEY)
MONMSG MSGID(CPF9892) EXEC(DO) /* Not found */
SNDESCMSG MSG('Key ' *CAT &KEY *TCAT ' not found ')
ENDDO /* Not found */
CHGVAR &FIELDB (&FIELDB + 1)
UPDDBR RCD(&RCD1)
CLSDBR
SNDPGMMSG MSG('Key ' *CAT &KEY *TCAT ' was updated.')
ENDPGM
Use of Substring
----------------
The CLPDBR tool only operates on a record buffer basis. If you do
not use a function such as CRTCLPDCL to create a data structure as
the record format, you must use the CLP substring capability to build
and extract from the buffer. The CLP data structure function was
added in V5R4. For releases prior to V5R4, you must use a substring
technique.
To provide for general purpose use, the size of the buffer returned
from RDDBR is always 5000 bytes. On RDDBR, you must declare the RCD
return variable as 5000 bytes. You may provide a variable that is
less than 5000 bytes on the UPDDBR, WRTDBR, or POSDBR commands.
A typical substring operation would be:
CHGVAR %SST(&RCD 11 10) &VARA
This would move &VARA to the &RCD variable beginning at position 11
for 10 bytes.
The DSPFMT TAA command provides a simple means of determining the
From/To positions of a field in a file.
If you have a multi-part key, you must also use substring or
concatenate to create the key for such functions as RDDBR
TYPE(*EQUAL) or POSDBF with a key.
Because CL does not have a function to handle placing a *DEC variable
value inside a string in a packed representation, zoned decimal
fields are much easier to work with.
The first example will assume a zoned decimal field exists in the
data base record. Assume you have a data base file ABC with a record
defined as:
A R RECORD TEXT('CLP files record')
A FLDA 10 COLHDG('File')
A FLDB 5S 0 COLHDG('Zoned decimal')
Typical CL code to read the record and substring out the fields would
be:
DCL &RCD *CHAR LEN(5000)
DCL &FLDA *CHAR LEN(10)
DCL &FLDB DEC LEN(5 0)
.
OPNDBR FILE(ABC)
RDDBR RCD(&RCD)
CHGVAR &FLDA %SST(&RCD 1 10)
CHGVAR &FLDB %SST(&RCD 11 5)
If &FLDB is a packed decimal field, 3 bytes make up the field in the
data record. There is no built-in function to allow packed decimal
data inside a character string to be moved to a decimal variable.
Two TAA tools may be used to convert from/to decimal variables. The
following would be typical coding:
DCL &RCD *CHAR LEN(5000)
DCL &FLDA *CHAR LEN(10)
DCL &FLDB DEC LEN(5 0)
DCL &WRKDEC *DEC LEN(15 0)
DCL &CHAR8 *CHAR LEN(8)
DCL &HEX00S *CHAR LEN(8)
CHGVAR &HEX00S X'0000000000000000'
.
OPNDBR FILE(ABC)
RDDBR RCD(&RCD)
CHGVAR &FLDA %SST(&RCD 1 10)
CHGVAR &CHAR8 &HEX00S /* Initialize */
CHGVAR %SST(&CHAR8 6 3) %SST(&RCD 11 3)
MOVCHRDEC DECOUT(&WRKDEC) CHRINP(&CHAR8)
CHGVAR &FLDB &WRKDEC
/***************************************/
/* */
/* Your processing to change values */
/* */
/***************************************/
CHGVAR %SST(&RCD 1 10) &FLDA
MOVDECCHR CHROUT(&CHAR8) DECINP(&FLDB)
CHGVAR %SST(&RCD 11 3) %SST(&CHAR8 6 3)
UPDDBR RCD(&RCD)
MOVCHRDEC extracts from a *CHAR LEN(8) variable (with the value right
adjusted) to a *DEC field. The decimal field must be declared as
*CHAR LEN(15 0). If the value has 2 decimal positions, you must use
divide by 100 to place the value in another decimal variable.
MOVDECCHR does the inverse (moves from a decimal field to a *CHAR
LEN(8) field). The decimal field may be declared up to 15 digits in
length, but must have 0 decimal positions.
Performance
-----------
The main intent of the CLPDBR tool is to bring full data base
functions to CL programs that require a small amount of data
handling. You should not consider the tool as a replacement for
performance sensitive applications.
You would find an RPG program faster in performing reading, updating,
and adding records.
The CL program capability of DCLF/RCVF to read a data base file
provides better performance than CLPDBR. If you don't need the
function of CLPDBR, use the system support if a significant number of
records must be read.
CLPDBR escape messages you can monitor for
------------------------------------------
The CPF9898 escape message is sent for a variety of errors from
several commands for invalid situations such as the file was open for
input and you have requested WRTDBR. In this case, the file will be
closed before the escape message is sent.
CPF9898 is also sent if the OPNID does not exist. Since the file is
unknown, it cannot be requested to be closed.
The following escape messages are intended to be monitored for in
your program. They do not cause the file to be closed. For example,
if the record cannot be found using RDDBR, it is expected that you
will monitor and may want to read again for a different record.
OPNDBR TAA9896 The OPNID is already open
RDDBR TAA9892 The record could not be found
(also sent for 'end of file')
TAA9895 Locked record found
UPDDBR TAA9893 Duplicate key
WRTDBR TAA9893 Duplicate key
TAA9894 Write to an active RR number
POSDBR TAA9892 The record does not exist
Escape messages from based on functions will be re-sent.
Comparison with RPG data base operations
----------------------------------------
RPG CLPDBR
--- ------
OPEN OPNDBR
CLOSE CLSDBR
CHAIN RDDBR OPER(*EQUAL)
READ RDDBR OPER(*NEXT)
READE RDDBR OPER(*NEXTEQ)
READP RDDBR OPER(*PREV)
READPE RDDBR OPER(*PREVEQ)
SETGT POSDBR KEYOPTION(*GT)
SETLL POSDBR KEYOPTION(*LE) or *EQ
WRITE - Note 1 WRTDBR
UPDATE UPDDBR
DELETE DLTDBR
UNLOCK - Note 2 RLSDBR
COMMIT/ROLBK Not supported
KLST/KFLD Not supported - Note 3
FEOD Not supported
FORCE Not supported
Note 1 - The normal write occurs to the end of the file. A write to
a relative record number can be used if the record is deleted.
Note 2 - Release of a record lock in RPG is done via UNLCK or UNLOCK
or by exception output to the record with no fields specified.
Note 3 - The key must be built in a single field. The CL substring
and concatenate functions must be used. The MOVDECCHR may be used
when assembling a key containing packed data.
The RDDBR command also allows options for *FIRST and *LAST to
immediately read records without first positioning to the beginning
or end of file.
Comparison with RPG compiler actions
------------------------------------
The RPG compiler checks to see when an operation such as WRITE is
used that the file will be opened to allow adding of records. If
not, the compilation fails.
The CLPDBR commands cannot be checked during compilation because the
CL compiler treats each command separately. Consequently, a run time
error occurs if you attempt to use a command like WRTDBR when the
file was opened for input.
File cursor positioning
-----------------------
The file cursor positioning is intended to operate similar to RPG.
Each file/member opened has a separate file cursor.
The cursor position is moved by the successful use of a RDDBR or
POSDBR command. The cursor position is not changed by a WRTDBR,
UPDDBR, DLTDBR, or RLSDBR command.
If an error occurs (such as a key does not exist for a random read of
RDDBR), the cursor position may be lost. Good practice would be to
re-establish the cursor position before doing a RDDBR TYPE(*NEXT).
Record locking considerations
-----------------------------
A record lock is placed on a record if OPNDBR specifies OPNTYPE(*ALL)
and the RDDBR command uses the default of LOCK(*OPNTYPE). You cannot
lock a record if the file is open for input or output only.
A record lock is required in order to use the UPDDBR and DLTDBR
commands. RDDBR must be used to achieve the lock.
You may release a record lock by using RLSDBR. If no lock exists, no
error occurs.
You may read a record without locking by specifying LOCK(*NO) on
RDDBR.
POSDBR does not lock a record.
Handling of decimal fields
--------------------------
Binary fields are always changed to *INT types.
Because the CL compiler does not support:
** Zoned fields (only packed fields are supported internally).
** A method of moving a packed field within a larger character
variable to a decimal field.
special handling is needed in some situations.
** Data structure use of CRTCLPDCL.
Packed fields are handled easily as they are defined within
the data structure with their proper length.
Zoned fields cannot be defined as *DEC because they would have
a packed length rather than a zoned length. For this reason,
they are defined as *CHAR and you must move the data to a *DEC
variable in order to process it as decimal data.
** Non-Data structure use of CRTCLPDCL (DSNAME = *NONE).
Zoned fields are defined as *CHAR fields. You must move the
data to a *DEC variable in order to process it as decimal
data.
Packed fields are defined as *CHAR fields. Use the TAA
command MOVCHRDEC to move the bytes to a decimal field. Use
the TAA command MOVDECCHR to move the bytes back to the *CHAR
field if you want to update the data.
Handling of multiple part keys
------------------------------
Randomly accessing a record which has multiple part keys are easily
handled by using a data structure to define the key field. Packed
keys are also easily handled.
Assume you have a file definition of:
A R RCD3
A FIELDA 5
A FIELDB 3 0
A FIELDC 6
A FIELDD 20
A K FIELDA
A K FIELDB
A K FIELDC
You would define a data structure for the key such as:
DCL VAR(&KEY) TYPE(*CHAR) LEN(13)
DCL &KEY1 TYPE(*CHAR) LEN(5) +
STG(*DEFINED) DEFVAR(&KEY 1)
DCL VAR(&KEY2) TYPE(*DEC) LEN(3 0) +
STG(*DEFINED) DEFVAR(&KEY 6)
DCL VAR(&KEY3) TYPE(*CHAR) LEN(6) +
STG(*DEFINED) DEFVAR(&KEY 8)
When a specific key is needed, move the key information to the &KEY1,
&KEY2, and &KEY3 fields and then:
RDDBR TYPE(*EQUAL) RCD(&xxx) KEY(&KEY)
Use of RCLDBR
-------------
The RCLDBR command is designed for cleanup of the current job when
files are left open or the activation group used by the CLPDBR
function exists. RCLDBR is not needed if the files are closed
properly with the CLSDBR command.
It is expected that when first using the CLPDBR functions, you will
make mistakes such as:
OPNDBR FILE(xxx) OPNTYPE(*INP)
WRTDBR RCD(&yyy)
Because the file was opened for 'input only', the WRTDBR command will
fail. In this case, the file will be closed by the WRTDBR command so
there is no need for RCLDBR.
However, if you specified:
OPNDBR FILE(xxx) OPNTYPE(*INP)
RDDBR RCD(&yyy)
and no records exist in the file, RDDBR will send the TAA9892 escape
message. The file will remain open. If you do not monitor for the
'end of file' condition, the program will abnormally end without
closing the file. You cannot successfully call the program again in
the same job because the file is still be open. To close the file
and start over, enter:
RCLDBR
RCLDBR deletes any data areas in QTEMP that were created by OPNDBR,
ends the main processing program, and reclaims the activation group.
It is not an error to use RCLDBR if there is nothing for it to do.
Security and Integrity
----------------------
The CLPDBR tool uses normal system security to determine who can read
or change a file using commands such as UPDDBR.
Because of the requirement that level checking is enforced, the
integrity can be better than the system approach which allows
LVLCHK(*NO). An exception exists for *ALLOBJ users who may specify
OPNDBR with LVLCHK(*NO).
You may not want every programmer to be able to use CLPDBR and
particularly against some files. The tool provides different levels
of control to allow you tailor the security to meet your needs. The
following describes the important considerations.
** An *ALLOBJ user must enter CRTDBRCTL to create the the DBRCTLP
and DBRCTLL files.
** The user running a command such as OPNDBR must be authorized
to the DBRCTLP file.
** The CLPDBR tool requires that any file to be opened must be
identified in a DBRCTLP file. Once the file is identified in
the DBRCTLP file, any programmer may use the CLPDBR functions
to write a program using the file. Any user who is properly
authorized to the file may use the program.
** Multiple DBRCTL files may be created in different libraries.
** To add a record for a named file, the WRKDBRCTL command is
used. The command is *PUBLIC *USE, but the user running the
command must have at least *CHANGE authority to the DBRCTLP
file.
** In addition to being able to change the DBRCTL files, the user
entering WRKDBRCTL must have at least one of the following 1)
*ALLOBJ authority 2) All rights to the file that is named
(such as being the owner) or 3) the 'Object Reference' right
to the DBRCTLP file. The 'Object Reference' function is
intended for the case where you want specific programmers (or
*PUBLIC) to be able to use CLPDBR when they do not have all
rights to the named file. The use of the 'Object Reference'
right was chosen to allow this special function to be
performed. The normal use of 'Object Reference' is intended
for 'referential integrity constraints' which does not apply
for the DBRCTLP file.
** The OPNDBR and record processing commands such as RDDBR may
only be used in a CL program. There is no check made when the
command is entered via a source editor or when the program is
created that either the programmer or a user of the program
will be able to perform the function. This is controlled by
the use of normal system security.
** The level ID of the file when it was added to the DBRCTLP file
is checked to see if it is still the same. If not an escape
message is issued.
An exception exists for *ALLOBJ users who may specify OPNDBR
with LVLCHK(*NO). This allows a variable file name to be
processed by CLPDBR.
** An error will occur if you pass more data on WRTDBR or UPDDBR
than the current record length of the file.
** An error will occur if you pass more data for the key on RDDBR
or POSDBR than the current key length of the file.
** None of the CLPDBR commands use the program adopt function.
Security approaches
-------------------
Users with *ALLOBJ special authority may do whatever they want.
This discussion focuses on programmers who do not have *ALLOBJ
special authority.
** *RPGLIKE control. This is the default value on CRTDBRCTL and
would allow any user to enter a file name using WRKDBRCTL.
Once the file name has been entered, any programmer may write
a program using the CLPDBR functions. Any properly authorized
user to the named file may perform the functions as provided
by the program. This is essentially the same authorization
approach as used by RPG or DFU.
To achieve this level of control, an *ALLOBJ user creates one
or more sets of DBRCTL files and uses the default of
AUT(*RPGLIKE).
The *RPGLIKE function sets the *PUBLIC user to *CHANGE
authority and then adds the *OBJREF right to the *PUBLIC.
If the file is already created with *USE or *CHANGE, use:
EDTOBJAUT OBJ(xxx/DBRCTLP) OBJTYPE(*FILE)
Change the *PUBLIC user to *CHANGE if not already at *CHANGE.
Press F11 to display the individual object authorities. Enter
an X in the 'Ref' column. When 'Enter' is pressed, the
*PUBLIC user will display as 'USER DEF'.
** Owner control plus trusted users. This approach would allow
1) one or more trusted users to enter records into the DBRCTLP
file and 2) any owner of a file.
To achieve this level of control, an *ALLOBJ user creates one
or more sets of DBRCTL files and specifies AUT(*CHANGE).
EDTOBJAUT would be used:
EDTOBJAUT OBJ(xxx/DBRCTLP) OBJTYPE(*FILE)
The *PUBLIC user already has *CHANGE control which would allow
any user to add a record for a file that he was the owner of.
Each trusted user would be given *CHANGE authority and then
press F11 to display the individual object authorities for
that user. Enter an X in the 'Ref' column. When 'Enter' is
pressed, the user will display as 'USER DEF'. The trusted
users could then enter a record for any file.
** Owner (or all rights) control. This approach would allow any
programmer that owns a file (or has all rights to the file) to
enter a record for that file and use the CLPDBR functions on
the file.
To achieve this level of control, An *ALLOBJ user creates one
or more sets of DBRCTL files and specifies *PUBLIC *CHANGE.
** Tight control. An *ALLOBJ user creates a single set of DBRCTL
files (such as in QGPL) and specifies *PUBLIC *USE. The
*ALLOBJ user uses WRKDBRCTL to enter any file names to be used
by the OPNDBR command. This provides 100% control over what
files may be used with CLPDBR. Any programmer who is
authorized to a file that is named in DBRCTLP can use the
CLPDBR functions.
DSPPGMREF considerations
------------------------
When a CL program is created, a file that is used by a DCLF command
within the program is captured and made part of the OIR (Object
Information Repository) of the program. The information may be
accessed to the DSPPGMREF command.
The CLPDBR commands do not contribute to the OIR information. To
search for the usage of CLPDBR commands, consider the use of the
SCNSRC TAA command to scan for the OPNDBR command.
CLPDBR Processing
-----------------
The OPNDBR program finds the DBRCTLP file and checks to see if the
file name is described. If not, an escape message is issued. Any
file to be used must be specifically identified to the DBRCTLP file.
If the file name to be used exists in the file, the program extracts
the level ID which is stored in the record when the file was added by
WRKDBRCTL. The current level ID of the file is extracted from the
actual file and the two level IDs are compared.
If the level IDs differ, an escape message occurs. A change in level
ID means that you should review the current file definition with what
your program is using. Because the CLPDBR tool only operates on
record buffers, it is possible that the positions of the fields have
been changed. For example, if you increased the size of a field, you
probably need to adjust the data structure or the substring
operations in your program.
If you are using CRTCLPDCL, delete the generated specifications and
run CRTCLPDCL again.
When you have the program in synch with the file definition, use
WRKDBRCTL and the 2=Update option. This will update the record in
the DBRCTLP file with the current level ID.
Assuming the OPNDBR command has found the file and ensured the same
level ID, a data area in QTEMP is created with the name of the OPNID
parameter value. The data area acts as a file control block and is
used by all commands such as RDDBR. You should not delete this data
area during processing.
The file you specify on OPNDBR is opened to the system by the
TAADBKNR51 program. This is a common program that is used by all
CLPDBR functions in the same job. The program runs in the CLPDBR
activation group which is automatically created when the program goes
active.
When CLSDBR is run, the data area in QTEMP is deleted and the file is
closed to the system. The TAADBKNR51 program returns the number of
files that remain open for all uses of the CLPDBR function in the
same job. The default for the CLSDBR RCLACTGRP parameter is *YES to
end the activation group when there are no remaining files open for
the same job. With the default and no remaining files open, the
TAADBKNR51 program is called again and ends properly along with
reclaiming the CLPDBR activation group.
CRTDBRCTL Command parameters *CMD
----------------------------
DBRCTLLIB The library to contain the files DBRCTLP and
DBRCTLL.
SRCLIB The source library to use for the QATTDDS file
source. The default is *TAAARC. If a full license
exists, the source is used from the TAA Archive. If
a demonstration license exists, the source is used
from the QATTDDS file in the TAATOOL library.
A specific user library may be named, but the source
file must be QATTDDS.
AUT The authorization to the DBRCTLP file. The default
is *RPGLIKE. The user running a program with OPNDBR
must be able to read the DBRCTLP file (at least *USE
authority).
To fully understand the AUT options, see the tool
documentation discussion of 'Security and Integrity'
and 'Security approaches'.
*RPGLIKE is the default to provide a similar
approach as used by RPG where any user authorized to
CRTRPGPGM can write a program to use or change any
file he is authorized to. DFU uses a similar
approach. *RPGLIKE allows any user to enter a
record for any file into the DBRCTLP file and use
the CLPDBR functions in a CL program for any file he
is authorized to.
*CHANGE may be specified to allow any owner of a
file to enter a record in DBRCTLP and use the CLPDBR
functions. See also the *OBJREF right discussed in
the tool documentation.
*USE may be specified to allow a user of OPNDBR to
access the file.
*EXCLUDE may be used to prevent the *PUBLIC user
from any access to the DBRCTLP file.
DLTDBRCTL Command parameters *CMD
----------------------------
DBRCTLLIB The library containing the files DBRCTLP and DBRCTLL
which are to be deleted. The default is *LIBL. A
specific library or the special value *CURLIB may
also be specified.
WRKDBRCTL Command parameters *CMD
----------------------------
DBRCTLLIB The library containing the files DBRCTLP and
DBRCTLL. The default is *LIBL. A specific library
or the special value *CURLIB may also be specified.
OPNDBR Command parameters *CMD
-------------------------
FILE The qualified name of the file to be opened. The
library qualifier defaults to *LIBL. A specific
library or *CURLIB may also be used.
The file must be identified in the DBRCTLP file
found by the DBRCTLLIB parameter.
MBR The member of the file to be opened. The default is
*FIRST for the first member of a file. A specific
member of the file may be named or the special value
*LAST for the last member.
OPNTYPE The type of open to be performed on the file.
*INP is the default for 'input only' meaning the
file may only be read.
*OUT may be specified for 'output only' meaning that
file may only be written to by the WRTDBR command.
*ALL may be specified meaning any of the record
commands may be used on the file. If a RDDBR
command is used, the record returned will be locked
by default. A lock is required to use the UPDDBR or
DLTDBR commands.
SEQOPTION How the file will be processed.
*FILE is the default and means to use the definition
of the file (either keyed or arrival sequence).
*ARRIVAL may be specified to process a keyed file in
arrival order. This allows for reading in arrival
sequence or randomly accessing using a relative
record number.
OPNID The open ID assigned to the file. The default is
TAADFTDBR. A data area is created in QTEMP with the
OPNID name which acts as a control block for the
file. Do not delete the data area during
processing. CLSDBR will properly delete the data
area.
The use of the default works well with all of the
CLPDBR commands. However, if you need to have more
than one file open at a time, each additional file
must be assigned a unique OPNID and the same OPNID
must be used on commands such as RDDBR.
You may open the same file more than once at the
same time by assigning unique OPNIDs to the
additional uses.
LVLCHK Whether to use a level check for the file.
*YES is the default which means the file may only be
processed by entering a record for the file with
WRKDBRCTL which captures the level ID. At open
time, the level ID of the current file is checked
against the version stored when WRKDBRCTL was used.
If the level IDs do not match, the program must be
reviewed and a new level ID established with
WRKDBRCTL.
*NO may be specified if the user (or using an adopt
function) has *ALLOBJ authority. This allows one
time programs to use CLPDBR and for programs where
the file name is a variable.
Certain TAA Tools enter a name in this field. This
allows a LVLCHK(*NO) function for TAA controlled
files. Only specific TAA names for specific TAA
files are supported.
DBRCTLLIB The library containing the files DBRCTLP and
DBRCTLL. The default is *LIBL. A specific library
or *CURLIB may also be specified.
CLSDBR Command parameters *CMD
-------------------------
OPNID The open ID assigned to the file that will be
closed. The default is TAADFTDBR.
RCLACTGRP A *YES/*NO parameter that determines if the CLPDBR
activation group will be closed if there are no
remaining files open.
*YES is the default. When there are no other files
open in the same job for the CLPDBR function, the
main program is ended and the CLPDBR activation
group is reclaimed.
*NO should be specified if you have only one file
open at a time, but will be opening the same or a
different file again in the same job. When you no
longer need the CLPDBR function, specify *YES or use
the RCLDBR command.
RDDBR Command parameters *CMD
------------------------
TYPE The type of read to be performed. The OPNDBR
SEQOPTION determines whether a keyed file should be
opened using keys or by arrival sequence. An
arrival sequence file may only be opened in arrival
sequence.
*NEXT is the default to read the next record in the
file based on the file cursor. The cursor will be
set by a successful RDDBR or POSDBR command. If the
file has just been opened, *NEXT causes the first
record in the file to be read.
*EQUAL means to randomly access a record by a key
(KEY parameter) or a relative record number (RRNBR
parameter).
*NEXTEQ means to access the next record if it has
the same key as the current record. The file must
have been opened for keyed processing.
*PREV means to access the previous record from the
current cursor position. *PREV may be used when
processing either by key or arrival sequence.
*PREVEQ means to access the previous record if it
has the same key as the current record. The file
must have been opened for keyed processing.
*FIRST means to access the first record in the file.
*LAST means to access the last record in the file.
RCD The record buffer returned. The variable must be
declared as *CHAR LEN(5000) and can be a data
structure such as created by CRTCLPDCL. If a data
structure is not used, your program must substring
out of the buffer to access the required
information.
The CL compiler does not support zoned decimal
fields (either packed decimal or integer is
supported). 1) If you are using a data structure,
packed fields are easily handled, but zoned decimal
fields must be declared as *CHAR and you must move
the data to a *DEC field to process it. 2) If you
are using a substring approach, zoned decimal fields
are easily handled by moving to a *DEC field, but
packed fields are not. Packed fields can be handled
by the use of other TAA tools.
See the previous documentation for a more complete discussion.
KEY The key to the record to be read. The default is
*NONE.
If a value is specified, the OPNDBR command must
have specified keyed file processing. The value is
used if TYPE(*EQUAL) is specified. The exact key
must be passed to match a data base record.
It is an error to pass more data than the key length
defined for the file.
A maximum of 2000 bytes may be specified.
RRNBR The relative record number to retrieve a record for.
The file must have been opened for arrival sequence
processing and TYPE(*EQUAL) must be specified.
LOCK Whether to lock the record on a read. You must lock
a record in order to use the UPDDBR or DLTDBR
commands.
*OPNTYPE is the default meaning if you specify
OPTION(*ALL) on OPNDBR, the records are locked when
read by your program.
*NO may be specified when OPNTYPE(*ALL) is used to
prevent locking a record when it is read.
If OPNDBR specifies OPTION(*INP), records are not
locked on a read. OPTION(*OUT) prevents a read
operation.
RTNRRNBR The relative record number of the record that was
found. The relative record may be helpful if you
process by keys. This is an optional return
variable that if used must be specified as *DEC
LEN(10 0).
OPNID The open ID assigned to the file for the record that
will be read. The default is TAADFTDBR.
WRTDBR Command parameters *CMD
-------------------------
RCD The record buffer to be output to the file. A
variable is normally used to contain the data and
must be declared as *CHAR. The maximum length is
5000, but the length may be less.
It is valid to pass a value which is shorter than
the record to be written. Any data that exceeds the
length of the record defined to the system will
cause an error.
RRNBR The Relative Record number to be written. The
default is *NONE causing the record to be written at
the end of the file.
A specific Relative Record number may be used to
write to a deleted record if the file is opened in
arrival sequence and the record has been deleted.
OPNID The open ID assigned to the file for the record that
will be written. The default is TAADFTDBR.
UPDDBR Command parameters *CMD
-------------------------
RCD The record buffer to be updated to the file. A
variable is normally used to contain the data and
must be declared as *CHAR. The maximum length is
5000, but the length may be less.
A prior successful use of RDDBR must have occurred
to establish a lock on the record. The OPNDBR
command must have specified OPNTYPE(*ALL).
It is valid to pass a value which is shorter than
the record to be written. Any data that exceeds the
length of the record defined to the system will
cause an error.
OPNID The open ID assigned to the file for the record that
will be updated. The default is TAADFTDBR.
DLTDBR Command parameters *CMD
-------------------------
OPNID The open ID assigned to the file for the record to
be deleted. The default is TAADFTDBR.
The record must first be read by a RDDBR command to
establish a lock on the record. The OPNDBR command
must have specified OPNTYPE(*ALL).
POSDBR Command parameters *CMD
-------------------------
POSITION The position type to be used. Note that positioning
does not cause a record to be returned. Only the
cursor position to the record is set.
*KEY is the default for keyed processing. The file
must be opened for keyed processing. When *KEY is
specified, the KEYOPTION and KEY parameters must
also be entered.
*FIRST may be specified to position to the first
record in the file. When the file is opened, it is
already positioned to the first record in the file.
*LAST may be specified to position to the last
record in the file.
*RR may be specified to position to a relative
record number. The file must have been opened for
arrival sequence processing. When *RR is entered,
the RRNBR parameter must be entered.
OPNID The open ID assigned to the file to be positioned
to. The default is TAADFTDBR.
KEYOPTION The key option when POSITION(*KEY) is specified.
*EQ is the default meaning the value of the KEY
parameter is used to position and the value must
exist.
*GE may be specified to position to the key that is
greater than or equal to the KEY value entered.
This acts as the RPG SETLL function where an equal
indicator is not specified.
*GT may be specified to position to the key that is
greater than the KEY value entered. This acts as
the RPG SETGT function.
*LE may be specified to position to the key that is
less than or equal to the KEY value entered.
*LT may be specified to position to the key that is
less than the KEY value entered.
KEY The key value when POSITION(*KEY) is specified. The
file must have been opened for keyed processing.
If KEYOPTION(*EQUAL) is specified, the full key must
be specified and must exist in the file.
If any other KEYOPTION is specified, you may specify
less than the full key. It is an error to pass more
data for the key than is defined for the key length
of the file.
RRNBR The relative record number when POSITION(*RR) is
specified. The number must be greater than 0. The
number must be within the range of the records that
exist and cannot be a deleted record. The file must
have been opened for arrival sequence processing.
RLSDBR Command parameters *CMD
-------------------------
OPNID The open ID assigned to the file for the record to
be released. The default is TAADFTDBR.
The lock would be established by a RDDBR command.
No error occurs if a lock does not exist. The
OPNDBR command must have specified OPNTYPE(*ALL).
RCLDBR Command parameters *CMD
-------------------------
None.
Restrictions
------------
** The maximum record length is 5000 bytes.
** The maximum key length is 2000 bytes.
** The maximum number of files open in a job at one time is 2000.
** No support of FEOD.
** No support of commitment control.
** No special CCSID support. The default is to use the job's
CCSID.
** No null field support.
Prerequisites
-------------
The following TAA Tools must be on your system:
ADJVAR Adjust variable
CHKACTOBJ Check active object
CHKALLOBJ Check *ALLOBJ special authority
CHKOBJ3 Check object 3
CVTDAT Convert date
EDTVAR Edit variable
HLRMVMSG HLL Remove message
LOCKMSG Lock message
RSNLSTMSG Resend last message
RTVDAT Retrieve date
RTVDBFA Retrieve data base file attributes
RTVFMT Retrieve format
RTVOBJAUT Retrieve object authority
RTVOBJLST Retrieve object list
SNDCOMPMSG Send completion message
SNDDIAGMSG Send diagnostic message
SNDESCINF Send escape information
SNDESCMSG Send escape message
SNDSTSMSG Send status message
UPDPFILE Update PFILE keyword
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
OPNDBR *CMD TAADBKN QATTCMD
CLSDBR *CMD TAADBKN2 QATTCMD
RDDBR *CMD TAADBKN3 QATTCMD
UPDDBR *CMD TAADBKN4 QATTCMD
WRTDBR *CMD TAADBKN5 QATTCMD
DLTDBR *CMD TAADBKN6 QATTCMD
CRTDBRCTL *CMD TAADBKN7 QATTCMD
DLTDBRCTL *CMD TAADBKN8 QATTCMD
WRKDBRCTL *CMD TAADBKN9 QATTCMD
POSDBR *CMD TAADBKN10 QATTCMD
RLSDBR *CMD TAADBKN11 QATTCMD
RCLDBR *CMD TAADBKN12 QATTCMD
TAADBKNC *PGM CLP TAADBKNC QATTCL
TAADBKNC2 *PGM CLP TAADBKNC2 QATTCL
TAADBKNC3 *PGM CLP TAADBKNC3 QATTCL
TAADBKNC4 *PGM CLP TAADBKNC4 QATTCL
TAADBKNC5 *PGM CLP TAADBKNC5 QATTCL
TAADBKNC6 *PGM CLP TAADBKNC6 QATTCL
TAADBKNC7 *PGM CLP TAADBKNC7 QATTCL
TAADBKNC8 *PGM CLP TAADBKNC8 QATTCL
TAADBKNC9 *PGM CLP TAADBKNC9 QATTCL
TAADBKNC10 *PGM CLP TAADBKNC10 QATTCL
TAADBKNC11 *PGM CLP TAADBKNC11 QATTCL
TAADBKNC12 *PGM CLP TAADBKNC12 QATTCL
TAADBKNC21 *PGM CLP TAADBKNC21 QATTCL
TAADBKNC22 *PGM CLP TAADBKNC22 QATTCL
TAADBKNC29 *PGM CLP TAADBKNC29 QATTCL
TAADBKNR9 *PGM RPG TAADBKNR9 QATTRPG
TAADBKNR29 *PGM RPG TAADBKNR9 QATTRPG
TAADBKNR51 *PGM RPGLE TAADBKNR51 QATTRPG
TAADBKNP *FILE PF TAADBKNP QATTDDS
TAADBKNL *FILE LF TAADBKNL QATTDDS
TAADBKND *FILE DSPF TAADBKND QATTDDS
TAADBKNE *FILE DSPF TAADBKNE QATTDDS
CLPDBR *MENU
Structure
---------
OPNDBR Cmd
TAADBKNC CL pgm
TAADBKNR29 RPG pgm
TAADBKNC29 CL pgm
TAADBKNC22 CL pgm
CLSDBR Cmd
TAADBKNC2 CL pgm
TAADBKNR51 RPGLE pgm
TAADBKNC22 CL pgm
RDDBR Cmd
TAADBKNC3 CL pgm
TAADBKNR51 RPGLE pgm
TAADBKNC22 CL pgm
UPDDBR Cmd
TAADBKNC4 CL pgm
TAADBKNR51 RPGLE pgm
TAADBKNC22 CL pgm
WRTDBR Cmd
TAADBKNC5 CL pgm
TAADBKNR51 RPGLE pgm
TAADBKNC22 CL pgm
DLTDBR Cmd
TAADBKNC6 CL pgm
TAADBKNR51 RPGLE pgm
TAADBKNC22 CL pgm
POSDBR Cmd
TAADBKNC10 CL pgm
TAADBKNR51 RPGLE pgm
TAADBKNC22 CL pgm
RLSDBR Cmd
TAADBKNC11 CL pgm
TAADBKNR51 RPGLE pgm
TAADBKNC22 CL pgm
RCLDBR Cmd
TAADBKNC12 CL pgm
TAADBKNR51 RPGLE pgm
TAADBKNC22 CL pgm
Structure - Continued
---------------------
CRTDBRCTL Cmd
TAADBKNC7 CL pgm
DLTDBRCTL Cmd
TAADBKNC8 CL pgm
WRKDBRCTL Cmd
TAADBKNC9 CL pgm
TAADBKNR9 RPG pgm
TAADBKNC29 CL pgm
TAADBKND Dsp file
CLPDBR Menu
TAADBKNC21 CL pgm
TAADBKNE Dsp file
|
