Data Dictionary Maintenance - File Maintenance

File Management Software

Last Revised: 02/25/14

This option is used to identify the views that comprise a file maintenance application.

File Maintenance applications provide the ability to add, change, and delete records from a file.

File Maintenance applications are an automatic by-product of the Dynamo Data Dictionary. Before using the File Maintenance Option, define fields, key structure, and at least one standard view. File Maintenance supports file types DIR, SKx, and MKx.

If the Data Dictionary File Name is 4 characters or less, then you can link a File Maintenance application directly to the menu by using Menu Maintenance (SMU) and specifying a selection type of F, the Program/File as the company code (typically XX) followed by the Data Dictionary File Name, and the VDT Suffix to match that specified in File Maintenance Configuration, typically A. If the Data Dictionary File Name is more than 4 characters, you cannot currently attach it directly to the menu, but can write a very short program with a program name of 6 characters or less, which will invoke File Maintenance. See example below.

File Name The file name as previously defined in the data dictionary

VDT The VDT Suffix is used to enable multiple File Maintenance Configurations for the same data file. In most cases, only a single File Maintenance Configuration is needed per file, and the VDT is specified as A. Note the VDT must be specified in Menu Maintenance when connecting a File Maintenance application to the Dynamo menu.

KNUM File Maintenance applications typically use the primary key (KNUM 0) and the operator enters the segments of the key for KNUM 0. But there are some situations where an alternate KNUM is preferred. Using a KNUM other than 0 requires that the key be unique.

Allow Record Adds Normally Y, but can be set to N when operators should not be able to add new records to the file.

Allow Record Deletes Specify as N to prevent operators from deleting records from the file.

Delete Files

File Maintenance can prevent deletion of a record when there are records in another file with the same primary key as the file being maintained. File Maintenance can also remove records from related files that have a key whose starting characters match the key of the record being maintained.

In the example below, File Maintenance will dis-allow deleting of the record, if there are existing records in the IM01, AP12, or AP22 files with a KNUM 2, or in AP32 file with KNUM 1, that starts with the same characters of the key for the record to be deleted.

However, if there are no records in IM01, AP12, and AP22 that match, File Maintenance will delete the record being maintained, as well as all records in files VM03 and VM06 that have KNUM 0 keys that start with the same characters as the primary key of the record being maintained.

Display Fields

When operators run a File Maintenance application, they can either enter the key segments to uniquely identify a record or select an existing record from a list. The fields that are displayed in this list are specified here. In this example, 10 fields will be displayed. They happen to be all from the same file, although they can be from related files or programs that return a templated data structure. Refer to CDS037 for additional details. The Index column is only used when the Field is a repeating field.

The first screen shot below shows the Display Fields as specified in File Maintenance Configuration. The second screen shot shows the display in the File Maintenance application.

Add/Write/Delete Routine

This optional program name will be called to perform additional processing required. The ENTER list on the called program should be Y$,REC$,OLDREC$,MODE. See example below.

MODE	Usage
0	Called when adding a new record to the file, after key segment entry, and after the operator responds to the prompt "Add new record (Y/N)", but before entering any of the fields in the view. It could be used to set the default values for any fields in the record. Assign these default values to `REC$. OLDREC$` is not really used in this mode, although passed the same as `REC$` for consistency. Another use of this routine would be to prohibit adding records based on some custom logic. For example, if record adds are normally allowed, but disallowed based on an operator's security level, time of day, day of week, etc., then the routine should prompt the operator indicating that the record cannot be added, and then `EXIT 99` to inform File Maintenance not to proceed with creating the new record.
1	Called before writing the record. It could be used to record a log of fields changed, to update sort files, or to perform some additional validation. `REC$` contains the record as modified. `OLDREC$` contains the record before any changes were made. If the record is new, then `OLDREC$` will contain the key segments but all other fields will be as initialized by the bbx `DIM` verb. The called routine may change fields in `REC$` if necessary, but should not change any field that is a KNUM 0 key segment. The called routine should `EXIT 99` if the writing is disallowed returning the operator to the initial view to make any changes required.
2	Called before deleting the record. Used when custom logic is required before deleting a record. This could be simply to log the record deletion, or to perform additional tests to determine if record deletion is permitted. If the called routine determines that the record should not be deleted, then it should `EXIT 99` to cause File Maintenance to abort the deletion. Note that `REC$` represents the record as modified and `OLDREC$` is the value before any modifications have been made. Since File Maintenance does not write the record to the disc before calling this program, this program may need to use `OLDREC$` and not `REC$`, or `LET REC$=OLDREC$` (ignoring any changes made prior to the operator selecting the D option to delete the record).
3	Called after writing the record. In most cases, you can use the MODE=1 call to perform special processing when a record is being written. There are some circumstances where the Add/Write/Delete routine needs to access the record on the disc. In that case MODE=1 cannot be used because the record has not yet been written to the disc. MODE=3 can be used to perform special processing after the record has been written and can be read by the Add/Write/Delete routine. Note that exiting with `EXIT 99` has no effect when MODE=3.

Views

File Maintenance applications require the first view to be a Standard View. These views must be previously defined using the Views Option of Data Dictionary Maintenance (FMS). File Maintenance may however, include additional views. Additional Standard Views of the same file would be needed when there are more fields to be maintained than can be displayed in a single view. A Standard View can display up to 21 rows of data including key segments in a single column on a typical display with 25 rows. Group the fields that are related into another view when exceeding this limitation. The initial view will be displayed and maintained during File Maintenance. When the operator exits the initial view, they will be presented with a list of all views for this File Maintenance Configuration in the same sequence as specified.

View Type (T) column - displayed for convenience
V	Standard View
P	Called Program
F	Subsidiary File Maintenance

Options (Opt) column
blank	View is enabled
Y	View is omitted during File Maintenance (similar to deleting view, but easier to Un-omit later)
A	Automatically select this view when adding new records. For standard views, the user will be prompted for each field in the view as done with the first view.
R	After view is selected, upon return to list of views, primary view will be refreshed

Record Deletion

File Maintenance performs the following steps before deleting a record:

Checks each 'Delete File' set to 'Do not delete'. If there are any records in these files where the key starts with the same characters as the primary key being deleted, then the delete will not be allowed. In the example above, files XXIM01, XXAP12, XXAP22 and XXAP32 will be checked.
Calls the Add/Write/Delete program if specified. If this program exits with EXIT 99, then the record will not be deleted.
Deletes any records from the related 'Delete Files' that are set to 'Delete records'. In the example above, any records in files XXVM03 and XXVM06 will be removed where the starting characters of the key match the key of the record being deleted.
Deletes the record in the file being maintained.

Example of interfacing a File Maintenance application to the Dynamo Menu.
Note the Type should be "F", the Program/File Name should be the company code and 4 character File Name, and the VDT suffix should match that entered using File Maintenance Configuration.

If the Data Dictionary File Name is longer than 4 characters, then the following program can be used to call the File Maintenance Application. In this example, the company code used will be the active company (XX), the Data Dictionary File Name is CUSTOMERS, the VDT Suffix is A, and the data file name is "CUSTOMERS".

0100 REM "CUSTFM - Example of calling a File Maintenance 
			Application
			0110 LET DDKEY$=PAD("CUSTOMERS",10)+"A",DATFIL$="CUSTOMERS"

0120 CALL "CDS028",Y$,DDKEY$,DATFIL$; REM "Call File Maintenance 0130 RUN "CDS001"; REM "Return to Dynamo Menu

Example of an Add/Write/Delete Routine to display information when called

0100 REM "CDX110 - 05/18/07 Example of File Maintenance 
			Add/Write/Delete Routine
			0110 SETESC 8000; SETERR 8000
			0120 ENTER Y$,REC$,OLDREC$,MODE
			0130 CALL "CDS279",REC$,OLDREC$," File Maintenance Add/Write/Delete 
			Routine called with MODE="+STR(MODE)
			0140 GOTO EOJ

			8000 REM "Call Error/Escape Routine
			8010 CALL "CDS063",STR(TCB(5)),Y$,PGM(-2)
			8020 ON Y.ERRSTS GOTO 8030,8040,8050,8060
			8030 SETERR 0
			8040 RETRY
			8050 RETURN
			8060 RETRY

			9000 EOJ:
			9010 IF TCB(13) THEN EXIT
			9020 RUN "CDS001"

Example of an Add/Write/Delete routine used in View Maintenance

0100 REM "CDF173 - 05/17/07 View Maintenance - 
			Add/Write/Delete Routine
			0110 SETESC 8000; SETERR 8000
			0120 ENTER Y$,DD20$,DD20OLD$,MODE
			0130 ON MODE GOSUB ADD,WRITE,DEL,POSTWRITE
			0140 GOTO EOJ

			1000 ADD:
			1010 CALL "CDS069",1,1,0,0,"+option, F4=create view manually","A{|,2,,,,Y}PPopulate 
			view with all fields from data dictionary|CCopy existing 
			view",0,OPT$

1020 IF CTL<>4 THEN IF OPT$="C" THEN GOSUB COPY ELSE CALL "CDS181",ERR=1030,Y$,"XX",DD20.FILNAM$,PAR$,DD10$,TPL$,FLDCNT,FLDTPL$,FLD$[ALL],KNCNT,KNTPL$,KN$[ALL],DD12$,COTO$,FILNAMTO$; IF FLDCNT THEN GOSUB POPULATE 1030 RETURN 1100 POPULATE: 1110 CALL "CDS095",ERR=1280,DD21,"XXDD21","YUY",DD21$ 1120 LET DD21.FILNAM$=DD20.FILNAM$ 1130 LET DD21.VIEW$=DD20.VIEW$ 1140 LET IMIN=0 1150 IF KNCNT THEN LET KNTPL$=KN$[1],IMIN=LEN(KNTPL.FLDS$)/4 1160 IF IMIN>=FLDCNT THEN RETURN 1170 FOR I=IMIN+1 TO FLDCNT 1180 LET FLDTPL$=FLD$[I] 1190 IF (POS("FS_"=FLDTPL.FLDNAM$)=1 AND NUM(FLDTPL.FLDNAM$(4),ERR=1200)) OR (POS("FS"=FLDTPL.FLDNAM$)=1 AND NUM(FLDTPL.FLDNAM$(3),ERR=1200)) OR POS("UNUSED"=FLDTPL.FLDNAM$)=1 THEN CONTINUE 1200 LET DD21.FLDNAM$=FLDTPL.FLDNAM$,DD21.INDEX=0 1210 FOR J=1 TO FLDTPL.REPEAT 1220 LET DD21.SEQ=DD21.SEQ+1 1230 IF FLDTPL.REPEAT THEN LET DD21.INDEX=J 1240 WRITE RECORD(DD21)DD21$ 1250 NEXT J 1260 NEXT I 1270 LET DD20.TYPE$="V" 1280 RETURN 1300 COPY: 1310 LET CO$=Y.COMPCODE$ 1320 CALL "CDS050",Z1,Z2,Z5,Z6,"+company code to copy view from+",Z7,CO$,Y,Z8$,FMT$[ALL] 1330 IF CTL=4 THEN RETURN 1340 LET FILNAM$=DD20.FILNAM$,VIEW$=DD20.VIEW$ 1350 CALL "CDS037",CO$+"DD20",0,"","FILNAM|VIEW|TITLE",WINX,WINY,WINROWS,WINCOLS,"Select existing view to copy",COLORS$,SELRTN$,WHERE$,SORTBY$,MODE$,LIMITVAL,DD20$ 1360 IF CTL<>4 THEN GOSUB DD21 1370 RETURN 1400 DD21: 1410 CALL "CDS095",ERR=1480,DD21,"XXDD21","YUY",DD21$ 1420 CALL "CDS095",ERR=1480,DD21A,CO$+"DD21","YPX" 1430 READ (DD21A,KNUM=0,KEY=DD20.FILNAM$+DD20.VIEW$,DOM=1440) 1440 READ RECORD(DD21A,END=1460)DD21$ 1450 IF DD21.FILNAM$=DD20.FILNAM$ AND DD21.VIEW$=DD20.VIEW$ THEN LET DD21.FILNAM$=FILNAM$,DD21.VIEW$=VIEW$; WRITE RECORD(DD21)DD21$; GOTO 1440 1460 LET DD20.FILNAM$=FILNAM$,DD20.VIEW$=VIEW$ 1470 CLOSE (DD21A) 1480 RETURN

1500 WRITE: 1510 IF DD20.TYPE$<>"V" THEN CALL "CDS273",Y$,"XXDD21",0,DD20.FILNAM$+DD20.VIEW$ 1520 RETURN 1600 DEL: 1610 RETURN

1700 POSTWRITE: 1710 RETURN 8000 REM "Call Error/Escape Routine 8010 CALL "CDS063",STR(TCB(5)),Y$,PGM(-2) 8020 ON Y.ERRSTS GOTO 8030,8040,8050,8060 8030 SETERR 0 8040 RETRY 8050 RETURN 8060 RETRY 9000 EOJ: 9010 IF TCB(13) THEN EXIT 9020 RUN "CDS001"