Project Development Standards

CONTENTS

1. Account Setup

1.1 Structure of the Development Account

The development account for each project must be set up to contain the standard set of group names, as follows:

1. The system manager needs to create the account as follows:-

   NEWACCT accountname,MGR;CAP=AM,AL,GL,ND,SF,IA,BA,LG,PH,DS
                      ;ACCESS=(R,X:ANY;W,A,L:AC)
   

2. Logon as account manager and create these groups:-

   NEWGROUP COMMAND;ACCESS=(R,W,A,L,S,X:ANY)
   NEWGROUP COMPILE;ACCESS=(R,W,A,L,S,X:ANY)
   NEWGROUP DATA;CAP=IA,BA,LG;ACCESS=(R,W,A,L,S,X:ANY)
   NEWGROUP DICT;ACCESS=(R,W,A,L,S,X:ANY)
   NEWGROUP DOC;ACCESS=(R,W,A,L,S,X:ANY)
   NEWGROUP FORMS;ACCESS=(R,W,A,L,S,X:ANY)
   NEWGROUP JOB;ACCESS=(R,W,A,L,S,X:ANY)
   NEWGROUP LIB;ACCESS=(R,W,A,L,S,X:ANY)
   NEWGROUP PROG;CAP=IA,BA,PH,DS;ACCESS=(R,W,A,L,S,X:ANY)
   NEWGROUP SCHEMA;ACCESS=(R,W,A,L,S,X:ANY)
   NEWGROUP SOURCE;ACCESS=(R,W,A,L,S,X:ANY)
   NEWGROUP USL;ACCESS=(R,W,A,L,S,X:ANY)
   

   Those of you involved in Native Mode development will need the following groups:-

   NMLIB 	- equivalent to the LIB group
   NMOBJ 	- equivalent to the USL group
   NMPROG 	- equivalent to the PROG group
   

   These groups can be created automatically by the MENUIMP jobstream.

3. A group and user-id will also be needed for all the programmers who are going to be working on the system:-

   NEWGROUP name;CAP=IA,BA,PH,DS;ACCESS=(R,W,A,L,S,X:ANY)
   NEWUSER name;HOME=group;CAP=IA,BA,ND,SF,PH,DS
   

1.2 Description of Development Groups

The groups within the development account are to be used as follows:-

The following groups are for Native Mode development:

These groups can either be in addition to the other groups, to allow concurrent development in both Compatibility and Native Mode, or as replacements for the other groups if development is in Native Mode only. It should be possible to take the same application source code and compile it in either Mode without amendment - any slight changes required by the different versions of the COBOL compiler have been isolated to the standard copy library and COBOL macro file.

1.3 List of files to be copied

The following files will need to be copied from the STANDARD account into the corresponding groups of the development account.

These files will be copied automatically by the MENUIMP jobstream.

1.3.1 Compatibility Mode

These files are required for Compatibility Mode development:-

1.3.2 Native Mode

These files are required for Native Mode development:-

1.3.3 Common Files

These files are common to both Compatibility Mode and Native Mode development:-

1.4 The MENUIMP Jobstream

This utility will create the correct group structure and transfer the relevant files from the STANDARD account. It is initiated as follows:-

1. Logon as the account manager.
2. Type: FIJI MENUIMP.PUB.STANDARD

   This will ask the following questions:

3. Which Environment - Runtime, Development, or Both (R/D/B)?

   R = only those files concerned with running the Menu program, for those cases where the Menu software and application software are to be held in different accounts.

   D = only those files concerned with the development of application software, without the files to run the Menu program.

   B = both sets of files.

4. Native Mode or Compatibility Mode (NM/CM)?

   NM = will copy Native Mode files only.

   CM = will copy Compatibility Mode files only.

   (If both sets of files are required then this utility must be run twice)

5. Initial or Update run (I/U)?

   I = will include those files required for the initial setup.

   U = will exclude those files required for the initial setup.

   If the Development Environment is chosen certain files are required for the initial implementation only. These files are subsequently customised during the development of the project, and therefore should not be overwritten with the skeleton copies.

6. After the job has copied the relevant files it will update all the files in the JOB group to replace the account name from "STANDARD" to the application account name.

1.5 Application Macros

File STDMACRO.[NM]LIB contains the complete set of standard COBOL macros and should NEVER be modified to suit the requirements of a particular user application as the file is overwritten each time a new version of the standards is released.

Any additional macros that are required for a user application should be maintained in a separate file where they will not be affected by new versions of the standards. An initial version of this file is provided in xxxMACRO.LIB, where the `xxx' prefix should be changed to the 3-character mnemonic given to the application (see section 2.1.1).

This file initially contains only the %VERSION macro which is used within all user programs, both online and batch, to display the module version numbers and compilation dates. Please refer to section 8 of the manual entitled Menu System - Integration of Application Subsystems for more details on version number checking.

Any user macros which are added to this file must NOT use names that are already used within the standard macro file as the COBOL compiler will reject any duplicate macro names.

Every application module must therefore have two $INCLUDE statements in its source code, one for STDMACRO and another for xxxMACRO.

1.6 TESTCOMP, LIVECOMP, COMPALL Jobstreams

Copies of files TESTCOMP and LIVECOMP are included in the initial setup performed by the MENUIMP jobstream. The entries in the COMPILE group contain the FIJI jobstreams while the entries in the COMMAND group allow either of these jobs to be invoked with a single command.

1.6.1 Customisation

The jobstreams will require the following changes before they can be used:-

1. Reference to file `USERMACR' should be changed to `xxxMACRO' (see section 1.5).
2. If the system requires the use of the CODA-IAS copy library then the statement FILE IASLIB=IASLIB.LIB.!ias_version will need to be inserted near the line for IASMACRO.

Each jobstream has the ability to compile either in Compatibility or Native Mode, the choice being decided at runtime with the following question:

%Native Mode?(1)[Y=#GOTO NATIVE]

If the application is to be compiled in only one of these two modes then the choice can be hard-coded as follows:

• For Compatibility Mode only the single `%' sign at the start of the above line can be changed to `%%', turning it into a comment instead of a command.
• For Native Mode only the command #GOTO NATIVE should be inserted before the above line.

Some applications require the use of 3rd party run-time libraries (eg: to access the CODA-IAS link routines). For those developed in Native Mode it is possible to specify the names of these run-time libraries in the ;XL="<list>" option, either on the LINK statement which creates the program file, or the RUN statement itself. If it is decided to specify the XL list on the LINK statement then the compilation streams must be amended accordingly.

1.6.2 TESTCOMP

This jobstream is used to compile the program under development within the programmer's own group. The name of the source file should not be qualified as it is expected to exist within the logon group.

The program will be compiled into temporary file $OLDPASS using the development version of the COBCNTL file (to include the BOUNDS option) and with the compile-time switch X1 set to ON (to turn on the debug feature within the %ED and %DEBUG macros).

If the source is for a batch program the name of the eventual program file must be entered - it will be created in the logon group therefore cannot have the same name as the source file.

For Native Mode programs the LINK statement which creates the program file refers to a series of Relocatable Library (RL) files in order to satisfy any calls to external routines (eg: standard utilities, application utilities, etc). As there is no RL file for the IASLINK routines these must be obtained from an XL file, which can either be identified on the LINK statement or the RUN statement.

For Compatibility Mode programs there are no equivalent RL files, therefore all external routines must be available within an SL file, either within the programmer's group or the PUB group, and the program must be run with the ;LIB=G option.

If the source is for an online subprogram the object code will be transferred to a run-time library within the logon group (`SL' for Compatibility Mode, `XL' for Native Mode). This file will automatically be created if it does not already exist.

1.6.3 LIVECOMP

This jobstream is used to compile a program that has been completed by a programmer to a state in which it can be released to the client. This procedure also makes the program available to all others within the development account.

The source of the program in question must first be transferred from the programmer's development group into the SOURCE group, then deleted from the development group. To avoid uncontrolled compilations this job can only be streamed by user `MGR' (ie: the account manager).

Programs will be compiled WITHOUT the bounds option, and with switch X1 set to OFF, thereby turning off all debug code. For Native Mode programs the object code is optimised to level 1.

For batch programs (Compatibility Mode) the following steps are taken:-

• Compiled from <file>.SOURCE into <file>.USL
• Prepped from <file>.USL into <file>.PROG

For batch programs (Native Mode) the following steps are taken:-

• Compiled from <file>.SOURCE into <file>.NMOBJ
• Linked from <file>.NMOBJ into <file>.NMPROG

For online subprograms (CM) the following steps are taken:-

• Compiled from <file>.SOURCE into <file>.USL
• Use job USERPREP to merge all online modules with MENUSON.USL in order to create a new online program (xxxPROG.PROG).
• Use job SLPUB to create file SL.PUB to make all online modules available to all programmers within the development account.

For online subprograms (NM) the following steps are taken:-

• Compiled from <file>.SOURCE into RL.NMOBJ
• Use job USERLINK to merge all online modules with MENUSON.NMOBJ in order to create a new online program (xxxPROG.NMPROG).
• Use job NMXL to create files XL.NMPROG, CLOSEXL.NMPROG and CLOSERL.NMOBJ in order to make all online modules available to all programmers within the development account.

There is no automatic PREP/LINK with online subprograms as there may be several modules to be compiled before a new version of the online program can be created.

1.6.4 COMPALL

As well as a jobstream to compile a single module at a time each application should have available a job that will recompile the entire system. This is especially useful if a global change (eg: to a copy library or macro) needs to be incorporated into every program. It is often easier (and safer) to recompile everything than to accidentally miss a module out.

A sample jobstream is provided in COMPALL.JOB (or NMALL.JOB for Native Mode developments).

If required the compilations for the batch programs can be taken out and processed within a separate job.

1.7 Command Files and UDCs

The MPE/XL operating system has the ability to process command files as well as User Defined Commands (UDC's). Command files are less of an overhead on the system, and are more flexible than UDC's which require to be loaded via the SETCATALOG command, therefore command files should be used in place of UDC's wherever possible.

System-wide commands are held in the COMMAND group of the SYS account.

Account-wide commands should be held in the account's COMMAND group.

There is no equivalent with command files of a logon UDC, therefore the following procedure has been devised:-

1. For the equivalent of a logon UDC at account level create a file of commands called ACCLOGON in the PUB group.
2. For the equivalent of a logon UDC at user level create a file of commands called GRPLOGON in the user's home group.

Within the system UDC there is code that will invoke the contents of each of these files whenever you log on. Note that use of the CHGROUP command will not invoke the GRPLOGON file of the new group.

2. Naming Standards

2.1 General

2.1.1 System

The system will be known by a 3-character code, in the format aab where:-

2.1.2 Programs

All program files (source, relocatable, object) will be of the format aabnnns where:-

The only exception will be the online system, which will use the following files:-

• aab.USL, aabPROG.PROG (for Compatibility Mode)
• RL.NMOBJ, aabPROG.NMPROG (for Native Mode)

2.1.3 Jobs

All jobstreams will take their name from the most relevant program which they contain. All application jobstreams will be constructed so that they can be processed by FIJI/3000, if available. Those systems which are built around the standard Menu and Security System will have their jobstreams defined in the MENU database.

2.2 IMAGE Databases

Please visit here for the TurboIMAGE/XL Database Management System Reference Manual.

2.2.1 Database Names

The database will be named aabDB. If the system requires more than one database then each will have a different b character.

2.2.2 Dataset Names

All datasets will have meaningful names, and a prefix of either:

2.2.3 Data Item names

All data items will have meaningful names up to a maximum length of 15 characters. Even though IMAGE allows up to 16, the limit for VPLUS field names is 15 characters.

2.2.4 Copy Library Members

All file layouts will be defined in the application Copy Library (COPYLIB.SOURCE) and can be referenced with the name aabxx - where:

All copylib definitions should be generated using the COPYGEN program which creates entries in the format expected by the standard macros. Each data item will have a 3-character prefix which will be the bxx portion of the copylib name (see above).

The output generated by COPYGEN looks like the following:-

   01 <dataset-name>-LIST   PIC XX VALUE "@;".
   01 <dataset-name>-DSET   PIC X(16) VALUE "<dataset-name>".

   01 <dataset-name>-DATA.
      03 bxx-<item-name>    PIC 99.
      03 bxx-<item-name>    PIC X(40).
      etc.

2.2.5 Compound Items

It is possible to have the same item name appearing more than once in the same record definition - once as an item on its own and again as part of a compound item. For example, dataset D-INVOICE-LINE has one path (INVOICE-NO) to identify all lines for the invoice, and a second path (INV-LINE-NO, comprised of INVOICE-NO + LINE-NO) to uniquely identify a particular line within the invoice. When the dataset definition is generated by COPYGEN it cannot expand INV-LINE-NO into its component items as these are not defined within the IMAGE schema, which results in a record layout as follows:-

01 D-INVOICE-LINE-DATA.
   03 bxx-INVOICE-NO    PIC X(08).
   .............
   03 bxx-INV-LINE-NO   PIC X(10).

The definition for bxx-INV-LINE-NO must not be left like this as it does not identify its component parts. It is tempting to change it to the following:-

   03 bxx-INV-LINE-NO.
      05 bxx-INVOICE-NO PIC X(08).
      05 bxx-LINE-NO    PIC 9(02).

but this would cause compilation errors as the name `bxx-INVOICE-NO' is not unique. To overcome this problem the `bxx-' prefix should be dropped from all item names within the compound item, as follows:-

   03 bxx-INV-LINE-NO.
      05 INVOICE-NO   PIC X(08).
      05 LINE-NO      PIC 9(02).

This means that the two occurrences of INVOICE-NO must be referenced within a COBOL program in the following manner:-

• as `bxx-INVOICE-NO'
• as `INVOICE-NO OF bxx-INV-LINE-NO'

This method is safer than keeping the prefix and corrupting the item name in some subtle fashion in order to make it unique. This is important if it ever becomes necessary to search through a program in order to identify where a particular item is referenced - the fewer variations in the spelling of the name the easier the search.

2.3 VPLUS Forms

Please visit here for the VPLUS/V Data Entry and Forms Management Reference Manual.

2.3.1 VPLUS File Names

The `slow' forms file will be called aabFORM.

The `fast' forms file will be called aabFAST.

2.3.2 VPLUS Form Names

All form names will be constructed as bxxnn[s] where:

Because the forms within a forms file are arranged in name sequence this ensures that all members of the same forms family are grouped together, starting with the parent/father form. It also makes it obvious when you are dealing with a son form, and clearly identifies the name of the father form.

2.3.3 VPLUS Field Names

Wherever a field on a form has a direct relationship with a data item on a dataset the same item name must be used (hence the restriction of 15 characters for all database item names). Where the same item appears in an array each name must be suffixed by a 2-digit number which corresponds to its occurrence number on the screen. This makes it easy to construct the correct field name within a COBOL program (eg: in order to call VSETERROR after a validation error) by taking the item name and appending the current subscript/index number.

2.3.4 VPLUS Form Buffers

All VPLUS buffers will be defined as follows:-

01 bxxnn-SCREEN.
   03 bxxnn-<item name> PIC ....
   03 bxxnn-<item name> PIC ....
   03 etc.....

These form buffers can also be generated by the COPYGEN program. These definitions may be added to your copy library, but for large systems this may cause a huge number of entries, in which case it may be better to copy the buffer definition directly into the source code of the relevant program.

2.4 KSAM Files

KSAM files should only be used whenever a generic search facility or sequential access from the online system is required. The KSAM file should not contain any data that is not already available on the IMAGE database. This means that in the (rare!) event of a file corruption the entire file can be purged and rebuilt from the contents of the database.

The file name will be in the format bxxKSAM (and bxxKSAMK) where:-

2.5 Other Data Files

All other files (eg: sort files, temporary work files, print files) should include the program name plus a meaningful suffix, to make them unique. If several online modules refer to temporary files of the same name (eg: `WORK' or `TEMP') but with different sizes this will cause an error due to incompatible record lengths.

Note that no online module should use a temporary file which has the same name as its 8-character transaction identity as this is reserved for use by the USCREENOUT and USCREENIN facilities (see the manual on Standard Utilities for more details).

3. System Design Standards

3.1 Database Design

The database will be designed using standard IMAGE/3000 concepts, and all application programs will use standard IMAGE intrinsics in order to maintain or access the database. The main design considerations are as follows:-

1. There will be at least one password which allows global write access, and another which allows global read access. IMAGE security will be defined at dataset level only (ie: element-level security will not be used).
2. Detail datasets should not have more than 3 paths, and only one of these may be sorted.
3. All dates will be held in the format CCYYMMDD and should be defined in the IMAGE schema as K2 fields (unsigned two-word integer). This will allow them to be used as sort items if necessary.
4. On Native Mode processors the word size has been increased from 2 to 4 bytes, therefore consideration should be made when defining the size of data items and their position on datasets so that numeric items do not cross word boundaries, otherwise it will increase the number of instructions required to load/store the data item.

3.2 Transaction Logging/Backup/Recovery

3.2.1 Transaction Logging

This may or may not be implemented, but ALL database updates must be contained within Logical Transactions through the use of DBBEGIN and DBEND. This will allow logging to be turned on or off without requiring any program changes.

3.2.2 Backup

Database backups will be taken as sysdumps under user control.

3.2.3 Recovery

In the event of a failure the recovery process depends on whether transaction logging has been turned on or off:-

3.3 Data Dictionary

DICTIONARY/3000 will be used to record the full description of the entire system (eg: databases, datasets, data items, etc). This database will be maintained in the DICT group, and will be used primarily for documentation purposes, although it may also be used by a report generator (eg: QUIZ).

This data dictionary will be maintained for our purposes even if the client does not have the facilities to access it.

3.4 Programming Language

Unless justified otherwise application programs will be written using COBOLII to the latest level of ANSI standards, although certain functions may be satisfied by using the facilities available in QUIZ or BRW (Business Report Writer).

3.5 Menu and Security System

Unless justified otherwise the standard menu and Security program will be used as the control program for the entire system. This will handle all menu screens, user security, and access to all online and batch transactions. Details of this system can be found in the following manuals:-

• Menu and Security System - Functional Specification
• Menu and Security System - User Manual
• Menu and Security System - Application Integration

3.6 Online Transactions

All online transactions will be written as dynamic subprograms and will be contained within a single object file which will run under the control of the menu program.

3.7 Batch Transactions

All batch transactions will be initiated from a menu selection within the online system. The standard Menu and Security program has facilities for the definition of jobstreams, plus the ability to insert run-time parameters before a job is placed in the batch queue. If extra facilities are required they may be provided by the FIJI/3000 utility which can be invoked from the online menu.

3.8 Relocatable Library (RL) Files

3.8.1 Compatibility Mode RL's

Compatibility Mode RL files are not used due to the fact that when a program is prepped all modules that are referenced from an RL file are copied into a dummy segment (with the name `RL') in the resultant object file. Due to the large number of routines within our standard library (which excludes any additional routines that may be created for a user application) it is quite easy for this `RL' segment to exceed the maximum code size, thus making it impossible to create a program file.

3.8.2 Native Mode RL's

In Native Mode the limitation on code segment size has been removed, therefore more use can be made of RL files. The added advantage in Native Mode is that it is possible to compile directly into an RL, and on the LINK statement it is possible to specify a list of RL files, not just a single file.

The application should therefore make use of the following RL files, which should be referenced in the specified sequence:-

1. RL.NMOBJ for all the application online modules (USEROPEN, USERCALL USERCLOSE, etc) plus any other application routines.
2. STDRL.NMOBJ for all the standard utility routines (UERROR, etc).
3. CLOSERL.NMOBJ to contain copies of USERCLOSE and IASERROR only, to satisfy the call from UERROR in file (2) as it cannot refer back to an entry in file (1).

3.9 Executable Library (SL/XL) Files

3.9.1 Compatibility Mode SL's

The online system should not require the use of an SL file unless reference is made to utilities which are not under our control. If such utilities are required (eg: IASLINK) they should be contained in the SL file in the PUB group. It will be the responsibility of the client to update this file as and when updates to these utilities are received.

The SL file in the PROG group will contain our standard utilities which may be required by batch programs, which must therefore be run with the LIB=G parameter.

3.9.2 Native Mode XL's

None of the programs delivered to the client, whether online or batch, should require the use of any XL files except where non-Prolog utilities (eg: IASLINK) are referenced.

However, a series of XL files is required when testing online modules via the Menu and Security system:-

1. XL.<logon group> for the module being developed or modified.
2. XL.NMOBJ for all the other online modules (USEROPEN, USERCALL, USERCLOSE, etc) and any other application routines.
3. STDXL.NMOBJ for all the standard utilities (UERROR, etc).
4. CLOSEXL.NMOBJ to contain copies of USERCLOSE, IASERROR and UDUMMY only, to satisfy the call from UERROR in file (3) as it cannot refer back to an entry in file (2).
5. <file.group.account> for any foreign utilities (eg: IASLINK).

4. Program Design Standards (overview)

All programming will be in accordance with the standards laid down in the programming standards manual. These can be summarised as:-

4.1 Structure

All programs will be written in a modular fashion, using meaningful section and paragraph names. The PERFORM statement will only be used on section names. Limited use of the GO TO statement is allowed, but this must not pass control to a point outside the current section.

4.2 Documentation

All program source code will contain enough 'in-line' documentation (in the form of comment lines) so as to minimise the necessity of referring to external documentation for detailed explanations on the implementation of particular functions.

4.3 Standard Copy Library

The standard copy library (STANDARD.[NM]LIB) will contain the common communication area (COMAREA) used for all calls to IMAGE, VPLUS and KSAM intrinsics as well as all the standard utility subroutines. This area can be used by any online or batch program regardless of the application.

4.4 Application Copy Library

The application copy library (COPYLIB.SOURCE) will contain the definitions of all data files used within the individual system. These must be used to ensure compatibility between programs.

4.5 Error Messages

All error messages will be taken from a message catalog - this will ensure standardisation across the system, and also enable messages to be changed without recompiling individual application programs.

4.6 COBOL Macros

An extensive selection of COBOL macros will be provided for all of the common intrinsic calls, plus calls to the general-purpose subprograms. These macros will be defined in an editor file with the name of STDMACRO.[NM]LIB, and can be made available to each program by means of an $INCLUDE statement at the start of each COBOL source file.

Any additional macros required by individual systems should be maintained in a separate application macro file.

5. Database Updates

5.1 Locking

1. All database updates will be preceded by a single call to DBLOCK with the lock qualifier specifying as few entries as possible, and followed immediately by a call to DBUNLOCK.
2. The system design should avoid, if at all possible, the need for a logical transaction to update more than one database, as this would require multiple calls to DBLOCK (one for each database), which increases the possibility of a deadly embrace.
3. No locks must be in operation while waiting for a response from the user. All dialogue with the user must be complete before entering the LOCK-UPDATE-UNLOCK cycle.
4. All locking will be conditional, which means that control will be returned to the calling program even if all the specified locks have not been granted.
5. Subroutine UDBLOCK has code that, in the event that not all the required locks can be granted, will pause for one second and retry for up to 10 times before returning control to the calling program. If the lock has still not succeeded after the 10th attempt then the following events take place:-
   • Any locks that were successful are released.
   • The condition IMAGE-LOCK-FAILURE is set to TRUE.
   • An informative message is loaded into VIEW-WINDOW.
6. The calling program must therefore check for the above condition, and if set to true, must return to the user to display the window message, and allow the option to either retry the update or abandon the whole transaction.

5.2 Logging

1. Even though Transaction Logging may not be implemented in this system, all database updates must be contained within Logical Transactions through the use of `DBBEGIN' and `DBEND'.
2. This will allow Transaction Logging to be implemented at any time in the future without having to amend any of the online programs.
3. Unless justified otherwise, batch programs will not require the use of `DBBEGIN' and `DBEND' as, in the event of a failure, the database will be reloaded and the relevant transactions re-run.

5.3 Verification before Updating

1. Before applying any database updates each program must verify that the update is still valid - this allows for the possibility that some other update may have been performed on your data after the initial dialogue with your user.
   • Before an ADD, check that the record still does not exist.
   • Before a DELETE, check that the record still exists.
   • Before an UPDATE, re-read the record and check that it has not been changed by another user (refer to %DBCOMPARE in the following section).
2. It is not necessary to check that a record has been changed if the only update within your logical transaction is to increment/decrement a control total on that record. In this case all that is required is to re-read the record after the lock has been applied, add/subtract the transaction value from the control total, then update the record. This will allow other users to update the same control total at the same time without generating an error.
3. If this `pre-update verification' fails, a standard message must be issued to the user (eg. `010080:Transaction rejected - database has changed').
4. There will be no recovery from this situation - the user must redo the whole of the transaction which was rejected.

5.4 %DBCOMPARE Macros

1. In order to check that a dataset record has not changed since it was last read by the program one of the %DBCOMPARE macros should be used. These are not contained in the STDMACRO file, but in the STANDARD copy library entry "COMPARE" - this is because an additional data area is required to hold the latest copy of the record image for comparison with the original image.
2. This additional data area (DBC-RECORD-AREA) has been defined with a maximum size of 1024 bytes. If this is not sufficient then the COMPARE copy library member should be copied from file STANDARD to your own application copy library (COPYLIB.SOURCE) where the size can be increased to the required value.
3. The %DBCOMPARED macro is for comparing the contents of a Detail dataset. When the record in question is first read its record number (IMAGE-CUR-REC-NO) should be stored for use as one of the parameters to the macro when performing the comparison.
4. The %DBCOMPAREM macro is for comparing the contents of a Master dataset. The record number cannot be used because the record's address may have changed due to migrating secondaries, therefore the parameter value required to re-read the record will be the original key value.
5. The macro will re-read the designated record into a separate buffer (DBC-RECORD-AREA), which will be set to spaces if the requested record is not found. The contents of this buffer will then be compared with the original buffer (dataset-DATA), and if there is any difference the following events will take place:
   • The database will be unlocked.
   • The condition VEDIT-ERRORS is set to TRUE.
   • An informative message is loaded into VIEW-WINDOW.

5.5 Capacity Checking

1. In most cases capacity checking will not be carried out by application programs as frequent checks will be made by the user.
2. Where a single DBPUT occurs, it must take place prior to any DBUPDATE, without the need for any capacity checking.
3. Where a Logical Transaction requires a series of DBPUT's to the same dataset, the capacity of that dataset must be checked prior to the first DBPUT.
4. The macro %CAPCHECK will be used as in the following example:

    CA-10-CAPACITY.
   * Verify that there is enough room on the database
       %CAPCHECK(CA-10#,dataset-name#).
       IF IMAGE-SPARE-CAPACITY < number-of-new-records
          GO TO CA-65-NO-ROOM
       END-IF
   

5.6 Processing Sequence

The sequence of operations that should be followed in all database updates is as follows:-

1. End dialogue with the user.
2. Issue DBLOCK.
3. Perform secondary validation and/or capacity checking - if there is any failure issue a DBUNLOCK and return to the user.
4. Issue DBBEGIN.
5. Perform all updates (DBPUTs first).
6. Issue DBEND.
7. Issue DBUNLOCK.
8. Return to the user.

6. Screen/Form Design

1. All screens for online programs will be processed using standard VPLUS/3000 routines, on 262X terminals which support block-mode, function-key labels, and security video.
2. All forms will be defined as NO-REPEAT, CLEAR-BEFORE-NEXT. Screens comprised of multiple (ie. appending) forms will be avoided.
3. Maximum use will be made of single-form screens using `forms families'. This simplifies the use of VPRINTFORM (which provides a printed copy of the current form) and the HELP subsystem (which overwrites, then refreshes the current screen). This also takes advantage of the VPLUS optimisation feature whereby movement between screens within the same forms family does not require the whole screen to be repainted, only the data or field enhancements which have changed.
4. The value of NEXT-FORM-NAME will either be left as $HEAD or $END. The identity of the next form must be hard-coded into the program, and not taken from the form file.
5. All screens will contain a standard 2 line heading whose contents will be set by the menu/security program.
6. Function key labels will be set by the program, not taken from definitions within the forms file.
7. All display-only fields should have their data-type set to CHAR, so that VPLUS will not reject a value which cannot be amended.
8. Only those fields into which the user can enter data should have the enhancement set to inverse video, all others should have no enhancement.
9. Basic field validation, such as `required', `numeric' or `date' should be defined within the form using the relevant field processing specifications, thus avoiding the need for additional code within the application program.
10. Window messages that convey information or instructions will have the enhancement set to half-bright inverse video, whereas all error messages will be full-bright underlined inverse video - this is handled automatically by the standard screen-handling subroutines.
11. Window messages and function key labels should be defined using numbers from the message catalog (see following section).

7. Function Key Labels

1. Function key labels will indicate the options that are actually available at each stage of an application transaction (ie: do not show NEXT PAGE if there isn't one).
2. Certain function keys may be used for similar purposes within many of the online programs. Wherever possible the same function key (and its corresponding label) should be used throughout the system. Function keys f6, f7 and f8 are system constants and should not be changed.
3. The remaining keys (f1 - f5) can be set as and when necessary by the individual program. The following list is intended as an example of common labels and their functions:-

8. Message Catalog

1. All application messages that appear in the VPLUS window will be given a six-digit number, which will be made up from a two-digit SET number and a four-digit MESSAGE-WITHIN-SET number.
2. The text associated with these SET/MESSAGE numbers will be maintained in a text file in the SOURCE group. This will be processed by the MAKECAT/GENCAT program to produce a compiled catalog in the PROG/NMPROG group.
3. Application messages should start from SET number 3 - sets 1 and 2 are reserved for standard messages and the menu/security system.
4. Certain messages require variable parameters - this is indicated by a `!' character in the text (one for each parameter).
5. Up to 5 parameters can be supplied with each message number. These parameters will be inserted into the message string by the GENMESSAGE/CATREAD intrinsic.
6. Provided that the UVPLUS routines are used for all screen handling, each application program need do no more than move the correct six-digit SET/MESSAGE number into VIEW-WINDOW prior to the next display of the form.
7. If any parameters are required they must follow the SET/MESSAGE number, separated by semi-colons, as in:-

   010100;parm1;parm2;parm3;parm4;parm5
   

   As the values for these parameters will normally come from data items within the program's working storage area, use the following statement to construct VIEW-WINDOW:-

   STRING "010100;" PARM1 ";" PARM2 ";" PARM3 ";" PARM4 ";" PARM5
       DELIMITED BY SIZE INTO VIEW-WINDOW
   END-STRING
   

8. Each parameter can be up to 40 characters long. The value inserted into the message will start with the 1st non-blank character, and end with the last non-blank character.
9. Function key labels can also be defined within the message catalog, but without the option of parameters. To avoid confusion with window messages these should either be given numbers at the high end of the range (ie: from 5000 onwards), or allocated to a separate set.

- END -