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.

Update procedures

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 screen above:

• The name of the update procedure being edited identifies the target file as SIRMON, the project as F6SNAPID, and the target procedure as MOPR-SYSOVR.
• The ./ I command in the third line tells SirLib to Insert after the line sequenced as 128 the lines up to the next ./ command.
• The ./ R command in the eighth line tells SirLib to Replace the line sequenced as 133 with the following line of code (up to the next ./ command prefix).
• Deletion of lines of code is handled in a similar way with ./ D.
• ./ * comments at the top of each update procedure specify the user, date, time, and source file for each change.

Control procedures

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.

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.

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 they are named the same as the target procedure but with a SEQ. prefix.

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 wants). 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.

SirLib advantages

The SirLib process for generating updates may sound complicated, but in practice it is simpler than most other change tracking systems. And it is far simpler in many ways than not using a change control system at all. In brief, the programmer:

1. Generates working and sequenced copies of a procedure with the Q command.
2. Makes any changes needed.
3. 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. 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 site uses. The assumed standard is for sites 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 a copying of the entire procedure 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 (Apply changes) in the SirLib main menu, and the production version of the procedure is ready for testing or distribution.

Another option is to distribute the FixFile itself. A site 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 it 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 that 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:

1. Making a working and sequenced copy of a procedure using the Q command
2. Making program changes to the working copy
3. 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 using the Apply changes (Reconfigure) option in the SirLib main menu.

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 (invoked by main menu option 1), you enter a new line 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 Definition List option allows entry of Project names, and allows PF key access to a documentation feature for the project.

Entry fields on the project definition 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 B and new features prefixed with F, followed by a version number and some mneumonic.
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.

See also

• SirLib
• SirLib implementation
• SirLib programmer's reference
• SirLib update example
• SirLib change control
• SirLib security
• SirLib reports
• SirLib configuration options
• SirLib problem resolution
• SIRLIBD record structure
• SirLib "getting started" steps
• SirLib date processing