|Author||:||A J Marston|
|Date Created||:||September, 1984|
|Date Revised||:||February, 1993|
The development account for each project must be set up to contain the standard set of group names, as follows:
NEWACCT accountname,MGR;CAP=AM,AL,GL,ND,SF,IA,BA,LG,PH,DS ;ACCESS=(R,X:ANY;W,A,L:AC)
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.
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
The groups within the development account are to be used as follows:-
|COMMAND||Contains the MPE/XL equivalent of UDC's (user defined commands).|
|COMPILE||Contains jobstreams to compile the system.|
|DATA||Contains the application database(s), and other data files.|
|DICT||Contains the Data Dictionary.|
|DOC||To contain all system documentation.|
|FORMS||Contains the application form file (slow and fast versions).|
|JOB||Contains jobstreams to create the message and help catalogs, and other general-purpose jobstreams.|
|LIB||Contains the copy library and macro file for developing software according to the PROLOG standards.|
|PROG||Contains runable program files, as well as the message and help catalogs.|
|SCHEMA||Contains the schema file for each application database.|
|SOURCE||Contains all the application source code and copy libraries.|
|USL||Contains the output files generated by the compiler which are used to create the runable program files.|
|<name>||A development group used as the programmer's work area. All software should be developed in a programmer's group and not transferred to the SOURCE group until it is complete.|
The following groups are for Native Mode development:
|NMLIB||Instead of the LIB group.|
|NMOBJ||Instead of the USL group.|
|NMPROG||Instead of the PROG group.|
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.
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.
These files are required for Compatibility Mode development:-
|STANDARD.LIB||Standard copy library (COMAREA).|
|STDMACRO.LIB||Standard macro file for use with COBOL85.|
|MENUSON.USL||Application system driver program (also contains USL versions of all utility subroutines).|
|COMPALL.JOB||Compile all batch/online programs.|
|USERPREP.JOB||Build application program.|
|USERHELP.JOB||Build application help catalog.|
|USERCAT.JOB||Build application message catalog.|
|MENUMSG.PROG||Compiled menu message catalog.|
|MENUHELP.PROG||Compiled menu help catalog.|
|SL.PROG||Segmented library file.|
These files are required for Native Mode development:-
|STANDARD.NMLIB||Standard copy library (COMAREA).|
|STDMACRO.NMLIB||Standard macro file for use with COBOL85.|
|MENUSON.NMOBJ||Application system driver program.|
|STDRL.NMOBJ||Library of standard subroutines.|
|CLOSERL.NMOBJ||Contains USERCLOS and IASERROR.|
|NMALL.JOB||Compile all batch/online programs.|
|NMPREP.JOB||Build application program.|
|NMHELP.JOB||Build application help catalog.|
|NMCAT.JOB||Build application message catalog.|
|NMXL.JOB||Build CLOSERL.NMOBJ, CLOSEXL.NMPROG and XL.NMPROG.|
|MENUMSG.NMPROG||Compiled menu message catalog.|
|MENUHELP.NMPROG||Compiled menu help catalog.|
|STDXL.NMPROG||Run-time library file.|
|CLOSEXL.NMPROG||Contains USERCLOS and IASERROR.|
These files are common to both Compatibility Mode and Native Mode development:-
|STDCAT.LIB||Standard message catalog (sets 1 and 2).|
|STDHELP.LIB||Standard help catalog.|
|XXXMACRO.LIB||Skeleton application macro file (where `XXX' should be set to your application mnemonic).|
|USERFORM.FORMS||Skeleton application formfile (contains forms HEAD, HELP, HELPD and VERSION).|
|COPYLIB.SOURCE||Skeleton application copy library.|
|USERCAT.SOURCE||Skeleton application message catalog.|
|USERHELP.SOURCE||Skeleton application help catalog.|
|USEROPEN.SOURCE||Skeleton subprogram to open user files.|
|USERCALL.SOURCE||Skeleton subprogram to call other modules.|
|USERCLOS.SOURCE||Skeleton subprogram to close user files.|
|UDUMMY.SOURCE||Skeleton subprogram to provide dummy entrypoints.|
|MENUSC.DATA||MENU database schema.|
|LIVECOMP.COMPILE||Sample FIJI job for `live' compilations.|
|TESTCOMP.COMPILE||Sample FIJI job for `test' compilations.|
This utility will create the correct group structure and transfer the relevant files from the STANDARD account. It is initiated as follows:-
This will ask the following questions:
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.
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)
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.
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.
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.
The jobstreams will require the following changes before they can be used:-
FILE IASLIB=IASLIB.LIB.!ias_versionwill 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:
#GOTO NATIVEshould 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.
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
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.
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:-
For batch programs (Native Mode) the following steps are taken:-
For online subprograms (CM) the following steps are taken:-
For online subprograms (NM) the following steps are taken:-
|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.|
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.
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:-
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.
The system will be known by a 3-character code, in the format
|aa||= alphabetic code identifying the client.|
|b||= alphanumeric code identifying the particular system (or subsystem).|
All program files (source, relocatable, object) will be of the format
|aab||= system code (from 2.1.1)|
|nnn||= program sequence number.|
|s||= identifier for sub-function or sub-program.|
The only exception will be the online system, which will use the following files:-
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.
The database will be named
aabDB. If the system requires more than one database then each will have a different
All datasets will have meaningful names, and a prefix of either:
|M-||for MANUAL MASTERS|
|A-||for AUTOMATIC MASTERS|
|D-||for DETAIL datasets|
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.
All file layouts will be defined in the application Copy Library (COPYLIB.SOURCE) and can be referenced with the name
aabxx - where:
|aab||is the system code (from 2.1.1)|
|xx||is unique for that database.|
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.
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:-
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.
The `slow' forms file will be called
The `fast' forms file will be called
All form names will be constructed as
|bxx||= the mnemonic associated with the most predominant dataset (see section 2.2.4)|
|nn||= the form sequence number, starting at 01|
|s||= a meaningful suffix indicating a SON form (the father form does not have a suffix)|
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.
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.
All VPLUS buffers will be defined as follows:-
01 bxxnn-SCREEN. 03 bxxnn-<item name> PIC .... 03 bxxnn-<item name> PIC .... 03 etc.....
|where ||= the form name as defined in paragraph 2.3.2 (suffixes are not required as all SON forms will use the same buffer as the father)|
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.
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
|bxx||= the dataset mnemonic from section 2.2.4|
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).
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:-
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.
Database backups will be taken as sysdumps under user control.
In the event of a failure the recovery process depends on whether transaction logging has been turned on or off:-
|OFF||= restore the last security sysdump and re-input all data up to the crash point.|
|ON||= use the relevant IMAGE recovery procedure.|
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.
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).
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:-
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.
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.
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.
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:-
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
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:-
XL.<logon group>for the module being developed or modified.
XL.NMOBJfor all the other online modules (USEROPEN, USERCALL, USERCLOSE, etc) and any other application routines.
STDXL.NMOBJfor all the standard utilities (UERROR, etc).
CLOSEXL.NMOBJto 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).
<file.group.account>for any foreign utilities (eg: IASLINK).
All programming will be in accordance with the standards laid down in the programming standards manual. These can be summarised as:-
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.
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.
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.
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.
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.
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.
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
The sequence of operations that should be followed in all database updates is as follows:-
|f1||PREVIOUS <item>||allows the user to flip back to the previous <item>.|
|f2||NEXT <item>||the opposite of PREVIOUS|
|f3||CANCEL/REFRESH||ignore current input, refresh screen to its original state|
|f4||RESTART||Restart current transaction from a blank screen|
|f5||CONTINUE||Accept current data, proceed to next screen before updating from this data|
|CONFIRM||Update using current data|
|UPDATE CONTINUE||Update using current data, more to follow|
|UPDATE END||Update using current data, end transaction|
|OTHER OPTIONS||Call the USELECT subroutine to allow the user to choose the next transaction|
|f6||Print the current form on the system printer|
|f7||HELP||Display any HELP text that has been established for the current transaction|
|f8||EXIT TRAN||Abandon current transaction, return to previous menu|
|PREVIOUS MENU||Return to a menu at a higher level|
|LOGON SCREEN||Return to the LOGON screen (ie: no more menus).|
|EXIT SYSTEM||EXIT from online system (ie: return to MPE)|
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
- END -