JAL: rename screen

2015-10-27T20:16:06Z

rename screen

← Older revision		Revision as of 20:16, 27 October 2015
Line 228:		Line 228:
	<p class="figure">[[File:SlibProjectDefList.png\|450px]]</p>		<p class="figure">[[File:SlibProjectDefList.png\|450px]]</p>

	The <b>Project</b> option allows entry of Project names, and allows PF key		The <b>Project Definition List</b> option allows entry of Project names, and allows PF key access to a documentation feature for the project.
	access to a documentation feature for the project.

	Entry fields on the ~~Projects~~ screen are:		Entry fields on the project definition screen are:

	<table class="thJustBold">		<table class="thJustBold">

JAL: more conversion cleanup

2015-10-22T20:33:09Z

more conversion cleanup

Show changes

JAL: add graphics

2015-10-22T00:42:53Z

add graphics

← Older revision		Revision as of 00:42, 22 October 2015
Line 141:		Line 141:
	Without <var class="product">SirLib</var>, [[SOUL]] change control might look like this:		Without <var class="product">SirLib</var>, [[SOUL]] change control might look like this:

	<p class="~~code~~">~~FIGCAP.~~Typical Model 204 procedure promotion. </p>		<p class="caption" style="width:450px">Typical Model 204 procedure promotion</p>
			<p class="figure">[[File:SlibProcPromotion.png\|450px]]</p>

	Typically, programmers make backup copies of procedures they are about		Typically, programmers make backup copies of procedures they are about
Line 164:		Line 165:
	difficulty of getting into production an error-free SOUL system.		difficulty of getting into production an error-free SOUL system.

	<p><b> ID=~~libr02</b~~> :~~FIGCAP~~.~~Change Management using SirLib~~</p>		<p class="caption" style="width:450px">Change Management using SirLib</p>
			<p class="figure">[[File:SlibChangeMgmt.png\|450px]]</p>

	The figure above shows a change promotion scheme using the <var class="product">SirLib</var> system.		The figure above shows a change promotion scheme using the <var class="product">SirLib</var> system.
Line 229:		Line 231:
	The resulting update procedure is the differences between the two.		The resulting update procedure is the differences between the two.

	<p~~><b>ID~~=~~libr04</b~~> ~~:FIGCAP.~~Update procedures linked to project via naming convention</p>		<p class="caption" style="width:450px">Update procedures linked to project via naming convention</p>
			<p class="figure">[[File:SlibUpdateProcsLinked.png\|450px]]</p>

	Once an update procedure is produced the programmer can delete the		Once an update procedure is produced the programmer can delete the
Line 237:		Line 240:
	<b>CONFIGURE</b> option in <var class="product">SirLib</var>.		<b>CONFIGURE</b> option in <var class="product">SirLib</var>.

	<p><b>ID=~~libr03</b~~> :~~FIGCAP~~.~~SirLib Functions~~</p>		<p class="caption" style="width:450px">SirLib Functions</p>
			<p class="figure">[[File:SlibFunctions.png\|450px]]</p>

	Management activity in the <var class="product">SirLib</var> system begins when a functional change is identified in a particular file in the local application.		Management activity in the <var class="product">SirLib</var> system begins when a functional change is identified in a particular file in the local application.
Line 250:		Line 254:
	previous updates have been applied.		previous updates have been applied.

	<b>~~SCREEN ID~~=~~LIBR14~~.~~Project screen~~</b>		<p class="caption" style="width:450px">Project screen</p>
			<p class="figure">[[File:SlibProjectDefList.png\|450px]]</p>

	The <b>Project</b> option allows entry of Project names, and allows PF key		The <b>Project</b> option allows entry of Project names, and allows PF key

Admin: 1 revision

2015-10-19T21:37:23Z

1 revision

← Older revision	Revision as of 21:37, 19 October 2015
(No difference)

JAL at 20:56, 16 October 2015

2015-10-16T20:56:52Z

New page

Managing changes to program code generally means controlling entire procedures
or files.
<var class="product">SirLib</var> manages changes, that is, differences between old and new
versions of procedures.

The central construct underlying the <var class="product">SirLib</var> system is that of an update procedure.
An update procedure is a <var class="product">Model 204</var> procedure containing lines of code to be
changed in another <var class="product">Model 204</var> procedure.

Interspersed with the lines of code are lines containing <var class="product">SirLib</var> commands and
sequence numbers which tell <var class="product">SirLib</var> 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 <var class="product">Model 204</var> procedure file called the
FixFile.

:SCREEN ID=libr051.An Update Procedure

The naming convention for <var class="product">SirLib</var> 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 <code>XMPLPROC</code>, and the project as <code>F2BALES</code>.
The remainder of the update procedure name identifies the target procedure
as <code>PRE_MAIN</code>.

The <code>./R</code> command in the first line tells <var class="product">SirLib</var> to <var>R</var>eplace
the lines sequenced as 328 through 329 with the following lines of code
(up to the next <code>./</code> command prefix).
The <code>./I</code> command tells <var class="product">SirLib</var> to <varI</var>nsert after the line sequenced
as 359 the lines up to the next <code>./</code> command.
Deletion of lines of code is handled in a similar way with <code>./D</code>.
<var class="product">SirLib</var> inserts <code>./ *</code> 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 <var class="product">Model 204</var> 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 <var class="product">SirLib</var> operations are
Base and Sequenced procedures.

When <var class="product">SirLib</var> attempts to apply an update against a procedure it looks
first for a procedure of the same name with a prefix of <code>BASE.</code>.
Such BASE., or Base, procedures are versions of procedures before any
updates have been applied to them through <var class="product">SirLib</var>.
If a Base procedure is found, <var class="product">SirLib</var> 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, <var class="product">SirLib</var> 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.
<var class="product">SirLib</var> always creates base procedures automatically; no user action is required to create a base.

Sequenced versions of procedures are produced when programmers use
<var class="product">SirLib</var> 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 <code>SEQ.</code>.
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 <var>Q</var> command, makes any changes needed, then generates the update procedure (the "differences") with an <var>X</var> command (<var>XCOMPARE</var>).
The update procedure is applied as part of a project when all parts of
that project are completed.

In <var class="product">SirLib</var>, the most important procedures are the <var>BASE.procname</var> 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 <var class="product">SirLib</var> 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 <var class="product">SirLib</var>, 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 <var class="product">SirLib</var>, 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 <var class="product">Model 204</var> online regions, can run a copy of <var class="product">SirLib</var> 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 <var class="product">SirLib</var>, [[SOUL]] change control might look like this:

FIGCAP.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.

 ID=libr02 :FIGCAP.Change Management using SirLib

The figure above shows a change promotion scheme using the <var class="product">SirLib</var> system.
In the simple flow diagram shown above changes for the various procedure
files are all generated into a single FixFile (here called <code>Changes</code>) in the development environment.
The <code>Changes</code> file is distributed or shared across Onlines, and the updates are applied in each region by a local copy of <var class="product">SirLib</var>.

The majority of configuration management tasks are invisible to
programmers using <var class="product">SirLib</var>.
Programmers work in <var class="product">SirPro</var>, which acts as a front-end to the <var class="product">Model 204</var>
editor and to the <var class="product">Model 204</var> command structure.
<var class="product">SirPro</var> 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 <var class="product">SirLib</var> is managing changes, special prefix commands are
supplied within <var class="product">SirPro</var>, that tell the <var class="product">SirLib</var> system that a managed update is taking place.
The commands are:
<table class="thJustBold">
<tr><th>Q</th>
<td><var>SEQUENCE</var>.

Tells <var class="product">SirLib</var> to generate working and "sequenced" copy of a procedure.</td></tr>

<tr><th>X</th>
<td><var>XCOMPARE</var>.

Generates an update procedure by comparing the working and sequenced procedure copies. Output is a procedure containing the differences.</td></tr>

<tr><th>N</th>
<td><var>NEW</var>.

Generates an update procedure for a new procedure.</td></tr>

<tr><th>K</th>
<td><var>KLOBBER</var>.

Generates an update procedure for a logical delete of a procedure.</td></tr>

<tr><th>Z</th>
<td><var>RESEQUENCE</var>.

Renumbers the internal sequence numbers for a procedure that has had many changes applied to it without the file being cutover.</td></tr>
</table>

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 <var class="product">SirLib</var> 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.
<var class="product">SirLib</var> 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 <var>Q</var> command, making
program changes to the working copy then executing an <var>X</var>
command against the copy to produce an update procedure.
The <var>X</var> 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.

ID=libr04 :FIGCAP.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
<var class="product">SirLib</var> 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 <var class="product">SirLib</var>.

ID=libr03 :FIGCAP.SirLib Functions

Management activity in the <var class="product">SirLib</var> system begins when a functional change is identified in a particular file in the local application.
In the <var class="product">SirLib</var> 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.

SCREEN ID=LIBR14.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:

<table class="thJustBold">
<tr><th>Status</th>
<td>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 (<tt>*</tt>) in this field. Care should be taken in commenting out projects that have dependencies in projects that are implemented after them.</td></tr>

<tr><th>Project ID</th>
<td>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 <code>B</code> and new features prefixed with <code>F</code>, followed by a version number and some mneumonic.</td></tr>

<tr><th>Description</th>
<td>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 <code>SIRLIB</code> reports.
Extra text can be added to a project via PF2 and this text is stored as data records in <code>SIRLIBD</code>.</td></tr>
</table>
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 <var class="product">SirLib</var> 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 <var class="product">SirLib</var> screens and
also by reviewing the procedure comments placed by <var class="product">SirLib</var> inside each
proc that has had an update applied to it.
Change status can also be seen in <var class="product">SirLib</var> reports.

==See also==
{{Template: SirLib topic list}}

[[Category: SirLib]]

SirLib implementation - Revision history

JAL: rename screen

JAL: more conversion cleanup

JAL: add graphics

Admin: 1 revision

JAL at 20:56, 16 October 2015