SirLib implementation
Managing changes to program code generally means controlling entire procedures or files. SirLib manages changes, that is, differences between old and new versions of procedures.
The central construct underlying the SirLib system is that of an update procedure. An update procedure is a Model 204 procedure containing lines of code to be changed in another Model 204 procedure.
Interspersed with the lines of code are lines containing SirLib commands and sequence numbers which tell SirLib where in the target procedure the lines to be changed are located. In other systems, update procedures are sometimes referred to as "deltas", or differences. All update procedures for one file are kept together, separate from the managed file in another Model 204 procedure file called the FixFile.
:SCREEN ID=libr051.An Update Procedure
The naming convention for SirLib update procedures identifies the target file for the update, the project to which the update links, and the procedure to be updated. Update procedure names must follow the following convention:
<filename>.<project>.<proc-name>
In the example above, the name of the update procedure being edited
identifies the target file as XMPLPROC, and the project as F2BALES.
The remainder of the update procedure name identifies the target procedure
as PRE_MAIN.
The ./R command in the first line tells SirLib to Replace
the lines sequenced as 328 through 329 with the following lines of code
(up to the next ./ command prefix).
The ./I command tells SirLib to <varInsert after the line sequenced
as 359 the lines up to the next ./ command.
Deletion of lines of code is handled in a similar way with ./D.
SirLib inserts ./ * comments at the top of each update procedure specifying the user, date, time and source file for each change.
The other kind of procedure contained in a FixFile is a Control procedure. Control procedures are Model 204 procedures that contain control data for the change management process. The control data is simply a list of Projects.
SCREEN ID=libr011.Control procedures contain project identifiers
Project identifiers are 8-character names of logical changes which allow physical changes (actual update procedures) to be grouped so they are always applied and backed together. Project identifiers are used as the second qualifier of update procedure names. Project identifiers may also be followed by a line of comment in the CONTROL.xxxxx procedure, as shown above.
Two more concepts central to SirLib operations are Base and Sequenced procedures.
When SirLib attempts to apply an update against a procedure it looks
first for a procedure of the same name with a prefix of BASE..
Such BASE., or Base, procedures are versions of procedures before any
updates have been applied to them through SirLib.
If a Base procedure is found, SirLib applies the changes as directed to the
Base version, deleting and replacing the previous executable procedure.
If no Base version of the procedure is found, SirLib assumes this is the first
managed change to be applied to this procedure, and it creates the Base version
before changes are applied (by copying the executable version into a Base
version).
Once a Base version of any procedure exists in a file it should never
be altered or deleted.
Base procedures should only be deleted as part of the Cutover process
described later.
Until the first update is applied to a procedure there is no need to create a separate Base copy of the procedure. The list of Base procedures in the managed file is the list of procedures that have had updates applied to them. SirLib always creates base procedures automatically; no user action is required to create a base.
Sequenced versions of procedures are produced when programmers use
SirLib facilities to make copies of procedures to work on.
Sequenced versions are created automatically and named the same as
the target procedure but prefixed with SEQ..
Internal sequence numbers are attached to each line of the original procedure
and stored as part of the sequenced copy.
When the programmer is finished making changes, this numbered version is used
as the comparison procedure for producing an update procedure.
Sequenced versions of procedures are kept by programmers for however long
changes are being made and update procedures are being generated (update
procedures can be regenerated as many times as a programmer wishes).
When the programmer is finished with the program changes, and a final version
of the update procedure has been generated, the sequenced and working version
of the procedure may be deleted.
While this process for generating updates sounds complicated, in practice it is simpler than most other change tracking systems, and far simpler in many ways than not using a change control system at all. The programmer generates working and sequenced copies of a procedure with the Q command, makes any changes needed, then generates the update procedure (the "differences") with an X command (XCOMPARE). The update procedure is applied as part of a project when all parts of that project are completed.
In SirLib, the most important procedures are the BASE.procname and the update procedures that apply to that Base procedure. If actual executable procedures are deleted they can be recreated by applying the updates to Base versions of the procedures. This is how updates are applied when a file is being reconfigured.
Change tracking and reporting can be done using the update procedure names alone — they supply the exact number of changed programs in a release, and coupled with the number of lines within the update procedures, managers can tell the number of lines of new or replacement code generated, and the date and time each update was completed.
Programmers need never be given update access to the actual production copies of procedure files. Development and testing is done by whatever method a shop uses. The assumed standard is for shops to define development subsystems (APSYs) with grouped procedure files, though this method is not a prerequisite for SirLib functioning.
When a programmer finishes working on a procedure an update is generated instead of the entire procedure being copied to a staging or production file. Once all update procedures are generated for a release, a manager reviews the updates to make sure they conform to local coding standards and that they are linked to projects existing in the control procedure. This level of monitoring, which used to be difficult if not impossible to do, is a simple task under SirLib, because the update procedures tend to be small, and because the internal comments clearly indicate who generated the new code, where it came from and when it was created. The manager applies the updates using option 2 in SirLib, and the production version of the procedure is ready for testing or distribution.
Another option is to distribute the FixFile itself. A shop with multiple Model 204 online regions, can run a copy of SirLib in each region. Update procedures can be distributed in the FixFile and applied on a region-by-region basis; this allows for faster backouts in production regions, and removes the complications of distributing each managed file.
SirLib operations overview
Without SirLib, SOUL change control might look like this:
Typical Model 204 procedure promotion
Typically, programmers make backup copies of procedures they are about to work on, either in the development file or in a "backup" file set aside for this purpose. They then work on the original procedure in the development file, integrating their changes either in the development file or when updates are sent to a test environment. Changes are promoted from development to test and from test to production either on a procedure-level or a file-level basis.
As shown in the illustration, often each file requires its own distribution or "staging" copy in each environment, and a mechanism is usually provided for copying procedures back from production to test and from test to development (the backward migration paths at the bottom of the picture).
On large projects the flow of change promotion can become extremely complex, with multiple development files and online environments, and various levels of integration both within and across onlines. Obviously the more complex the development path, the greater the difficulty of getting into production an error-free SOUL system.
Change Management using SirLib
The figure above shows a change promotion scheme using the SirLib system.
In the simple flow diagram shown above changes for the various procedure
files are all generated into a single FixFile (here called Changes) in the development environment.
The Changes file is distributed or shared across Onlines, and the updates are applied in each region by a local copy of SirLib.
The majority of configuration management tasks are invisible to programmers using SirLib. Programmers work in SirPro, which acts as a front-end to the Model 204 editor and to the Model 204 command structure. SirPro gives the SOUL developer an SPF-like "toolbox" with which to work, supplying prefix commands for copying, deleting, moving, renaming, editing and browsing SOUL procedures in a selected file. In addition, when SirLib is managing changes, special prefix commands are supplied within SirPro, that tell the SirLib system that a managed update is taking place. The commands are:
| Q | SEQUENCE.
Tells SirLib to generate working and "sequenced" copy of a procedure. |
|---|---|
| X | XCOMPARE.
Generates an update procedure by comparing the working and sequenced procedure copies. Output is a procedure containing the differences. |
| N | NEW.
Generates an update procedure for a new procedure. |
| K | KLOBBER.
Generates an update procedure for a logical delete of a procedure. |
| Z | RESEQUENCE.
Renumbers the internal sequence numbers for a procedure that has had many changes applied to it without the file being cutover. |
These commands are explained in more detail in SirLib programmer's reference.
Note in the previous figure, all the promotions paths are simplified. This is because SirLib allows updates to all managed files to be stored, managed and promoted within the same FixFile. Note also the elimination of the "copyback" path from the previous illustration. This path is generally a violation of a managed environment, and is tolerated because of the need to generate emergency fixes against production code, and because of the occasional requirement to re-align development and production procedures. SirLib eliminates this path by providing the tools to let users know the exact state of production code, and to duplicate the "update level" of production in any other environment.
Programming a managed update consists of making a working and sequenced copy of a procedure using the Q command, making program changes to the working copy then executing an X command against the copy to produce an update procedure. The X command compares the working copy which has changed, to the sequenced copy which will not have changed. The resulting update procedure is the differences between the two.
Update procedures linked to project via naming convention
Once an update procedure is produced the programmer can delete the working copy of the procedure and the matching sequenced version; the SirLib system generates the new production procedure by applying the update(s) against the Base procedure. This is done by a programmer, project leader or administrator via the CONFIGURE option in SirLib.
SirLib Functions
Management activity in the SirLib system begins when a functional change is identified in a particular file in the local application. In the SirLib Project screen (option 1), a new line is entered containing an 8-character project name and an optional description. PF key access allows an unlimited amount of optional documentation to be attached to a Project. The physical order of these project identifiers should not be altered once updates are linked to the identifiers, as this sequence specifies the order in which updates are applied. Updates that effect the same line of code will not apply correctly unless previous updates have been applied.
Project screen
The Project option allows entry of Project names, and allows PF key access to a documentation feature for the project.
Entry fields on the Projects screen are:
| Status | If this column is blank (or shows the default pad character, the underscore, the project is active and changes associated with this project will be included in subsequent file reconfigures and cutovers. To comment out a project, enter an asterisk (*) in this field. Care should be taken in commenting out projects that have dependencies in projects that are implemented after them. |
|---|---|
| Project ID | Project ID is an alphanumeric identifier of 1 to 8 characters that links together change decks containing related changes.
The project ID should conform to some meaningful pattern as established at the site. For instance, all bug fixes could be prefixed with |
| Description | As many as 72 characters of text can be added to the project. This descriptive text is displayed on the reconfigure screen and cutover screen, and in the SIRLIB reports.
Extra text can be added to a project via PF2 and this text is stored as data records in SIRLIBD. |
In a highly controlled environment the project leader may require that no changes occur in a file unless a project is entered first via the Project facility (options are provided to protect the ability to define Projects). In a less structured project, updates may be produced as programmers need to build them, and a project leader may later decide which will be included in a particular release by adding a project that links the updates in.
Along with making distribution files smaller this allows changes to be distributed and applied by SirLib directly in a production region. Generally, all changes for all procedure files can be kept in a single file, greatly reducing complex distribution problems. Operating in this manner allows changes to be backed out much faster. It also allows releases to be shipped to all sites and applied on a region-by-region or project-by-project basis. Status of the current configuration can be viewed in SirLib screens and also by reviewing the procedure comments placed by SirLib inside each proc that has had an update applied to it. Change status can also be seen in SirLib reports.