SirPro change management tools and functions: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision: SirPro from Stage)
m (mention RKWeb equivalents)
 
(9 intermediate revisions by the same user not shown)
Line 1: Line 1:
<!--Page automatically generated by CMSTOWIK EXEC and will be
==Overview==
** automatically replaced ** -- any manual edits will be lost.
Managed-update commands allow the manipulation and promotion of just the updates you make to a procedure, "deltas," instead of preserving and working with a sequence of updated copies of the entire procedure or entire procedure file. Managed-update commands are available in SirPro if the change management system, <var class="product">[[SirLib]]</var>, is active in the Online.
You've been warned.  ..  (Page built by JAL at the SIRIUS VM; file: FUNPGNEW SYSUT2) -->
<p class="note"><b>Note:</b>
<!-- Page name: SirPro change management tools and functions-->
Managed-update commands are not available in [[RKWeb]]; they require the SirPro TN3270 interface. </p>
 
<p>
Managed update commands are available if the change
The output from a managed-update command that produces update
management system, <var class="product">[[SirLib]]</var>, is active in the Online.
procedures contains a single-line comment describing the creator,
Managed update commands allow the manipulation and promotion of update procedures,
date, time, and source file for the change. </p>
"deltas," instead of entire procedures or entire procedure files.
The output from all managed update commands that produce update
procedures always contain a single-line comment describing the creator,
date, time and source file for the change.
<p>
<p>
The managed update commands are entered as prefix commands on the Procedure List screen
The managed-update commands are entered as prefix commands on the procedure list screen (see [[SirPro procedure-list operations]]).
(see [[SirPro procedure-list operations]]).
These prefix commands are:</p>
These prefix commands are:</p>


<table class="thJustBold">
<table class="thJustBold">
<tr><th>X</th>
<tr><th>X</th>
<td><b>Xcompare</b>.  
<td><b>XCompare</b>.  
<p>Compares two versions of a procedure and creates a third procedure containing the differences between the two. This output is an "update procedure", the physical unit managed by the change management system.</p></td></tr>
<p>Compares two versions of a procedure and creates a third procedure containing the differences between the two. This output is an "update procedure," the physical unit managed by the change management system.</p></td></tr>


<tr><th>Q</th>
<tr><th>Q</th>
<td><b>Sequence</b>.  
<td><b>Sequence</b>.  
<p>Creates both a working and sequenced version of a procedure that are the later input to Xcompare.</p></td></tr>
<p>Creates both a working and sequenced version of a procedure that are the later input to <var>XCompare</var>.</p></td></tr>


<tr><th>N</th>
<tr><th>N</th>
<td><b>New</b>. <p></p> Creates a "differences" update procedure similar to Xcompare, but which is the source for a new procedure.</td></tr>
<td><b>New</b>.  
<p>
Creates a "differences" update procedure similar to <var>XCompare</var>, but which is the source for a new procedure.</p></td></tr>


<tr><th>K</th>
<tr><th>K</th>
<td><b>Erase</b>.  
<td><b>Erase</b>.  
<p>Creates an update procedure similar to Xcompare output, but telling <var class="product">SirLib</var> to perform a logical delete on the procedure.</p></td></tr>
<p>Creates an update procedure similar to <var>XCompare</var> output, but telling <var class="product">SirLib</var> to perform a logical delete on the procedure.</p></td></tr>


<tr><th>Z</th>
<tr><th>Z</th>
<td><b>ReSequence</b>.  
<td><b>ReSequence</b>.  
<p>Creates a special update procedure to reorder the internal sequence numbers of a procedure.</p></td></tr>
<p>Creates a special update procedure to reorder the internal sequence numbers of a procedure.</p></td></tr>
<tr><th>U</th>
<td><b>Undo</b>.
<p>Like <var>Q</var>, but may only be executed against a change deck. It adds the change deck to the code for the working procedure, but <b>not</b> to the code from the sequenced copy. Added in version 7.5.</p></td></tr>
<tr><th>Y</th>
<td><b>Refresh</b>.
<p>Refreshes your local working copy of a procedure with changes that have been checked in by other programmers since the working copy was originally taken from
the source procedure file. Added in version 7.5.</p></td></tr>
</table>
</table>


Line 40: Line 46:
programmer in the <var class="product">SirPro</var>/<var class="product">SirLib</var>-controlled environment. This screen, and others like it,
programmer in the <var class="product">SirPro</var>/<var class="product">SirLib</var>-controlled environment. This screen, and others like it,
provide access to all procedure activity in <var class="product">Model&nbsp;204</var>.
provide access to all procedure activity in <var class="product">Model&nbsp;204</var>.
For details on the use of <var class="product">SirLib</var>, including the special commands for managed updates, see the <var class="book">[[Media:LibrNew.pdf|SirLib User's Guide]]</var>.
For details on the use of <var class="product">SirLib</var>, including the special commands for managed updates, see [[SirLib]].
Only the special Procedure List screen
Only the special Procedure List screen
prefix commands (Q, X, K, N, and Z) for creating and manipulating
prefix commands (<code>Q</code>, <code>X</code>, <code>K</code>, <code>N</code>, <code>Z</code>, <code>U</code>, and <code>Y</code>) for creating and manipulating managed updates are explained here.
managed updates are explained here.


The <code>Q</code>, <code>X</code>, <code>N</code>, <code>K</code>, and <code>Z</code> prefix commands are used to generate "working" base and sequenced copies of procedures and to generate updates from those copies.
The <code>Q</code>, <code>X</code>, <code>N</code>, <code>K</code>, <code>Z</code>, <code>U</code>, and <code>Y</code> prefix commands are used to generate "working" base and sequenced copies of procedures and to generate updates from those copies.
Type one of these managed update commands to the left of the selected procedure and press
Type one of these managed update commands to the left of the selected procedure, and press the Enter key.
the Enter key.
<var class="product">SirPro</var> then presents one of the managed update screens to get
<var class="product">SirPro</var> then presents one of the managed update screens to get
further details on the managed update.
further details on the managed update.
Those screens are shown in the following detailed sections.
Those screens are shown in the following detailed sections.


<div id="sequenc"></div>
{{Template:SirPro commands}}
==Sequencing: Creating working copies of procedures==
<!--Caution: <div> above-->
 
"Sequencing" is the managed update method by which programmers
make copies of procedures to work on.  In other systems, programmers
make backup copies of procedures and then work on the original.
In <var class="product">SirPro</var> programmers never alter the original program code, but execute <code>Q</code> commands to get working and sequenced copies from which
update procedures can be generated.
 
<p class="caption" style="margin-right:15em">Sequencing a procedure with the "Q" command</p>
 
Prefixing a procedure with the <code>Q</code> command on the Procedure List screen
tells SirLib to generate both a copy of the
selected procedure (the copy that the programmer will work on) and a
"sequenced" copy of the procedure (a copy containing sequence or
line numbers), which will later be used as comparison input for the
<code>XCOMPARE</code> command.
Building these copies is always the first step in generating a managed update.
The <code>Q</code> prefix command presents the Sequence Procedure screen, which has the following input fields:
 
<table class="thJustBold">
<tr><th>Output procedures</th>
<td>Enter a procedure file where <var class="product">SirLib</var> should create a working and <code>SEQ.</code> version of the selected procedure.</td></tr>
 
<tr><th>Password</th>
<td>An update password for this output procedure file is required unless the file is already open with update privileges.</td></tr>
 
<tr><th nowrap>UnSequenced procedure</th>
<td>Procedure name for the copy of the selected procedure that the programmer will be making updates to.  This defaults to the input procedure name.</td></tr>
 
<tr><th>Sequenced procedure</th>
<td>Procedure name for a copy of the procedure with each line prefixed by a sequence number, indicating line sequence and amount of update activity that has been applied in generating the working version.
<p>
The default procedure name for sequenced procedures is: </p>
<p class="code">SEQ.<i>procname</i>
</p>
<p>
This default prefix may be overridden if it conflicts with local APSY naming standards.</p></td></tr>
 
<tr><th>FixFile</th>
<td>Name of the file containing  Control and Update procedures for this file. Default file is <code>SIRLIBP</code>.</td></tr>
 
<tr><th>Password</th>
<td>A password for this FixFile is required unless the file is public or is already open with read privileges. The privileges for this password must allow the contents of procedures in the control file to be read.
<blockquote class="note">
<b>Note:</b> The control procedure name is displayed in the block of text above the FixFile input field for informational purposes only. This procedure, formatted as follows:
<p class="code">CONTROL.<i>filename</i>
</p>
<p>
Where <i>filename</i> is the name of the file from which the selected procedure is being copied. The control file must exist in the specified FixFile. This CONTROL procedure contains the project names active for this file. The update procedures that are pointed to by the project identifiers in the control procedure must be in the same file.</p></blockquote></td></tr>
 
<tr><th nowrap>Replace existing procedures</th>
<td>This field defaults to <code>N</code>, indicating that if a same-named procedure already exists in the destination procedure file, the attempt to copy over it will be aborted. To overwrite existing procedures, set this indicator to <code>Y</code>.</td></tr>
</table>
 
When the <code>Q</code> prefix command is executed from the Procedure
List screen, <var class="product">SirLib</var> looks in the
source file for a procedure named <code>BASE.<i>procname</i></code>, where
<i>procname</i> is the name of the selected procedure.
If no such procedure is found, <var class="product">SirLib</var> copies the selected
procedure into the specified target procedure in the specified Output file.
In addition, <var class="product">SirLib</var> generates a sequenced copy of the
procedure, named whatever the programmer specified in the <b>Sequenced
procedure</b> field on this screen.
The sequenced copy of the procedure is
identical to the unsequenced (or working) copy, except that each line
is prefixed with a sequence number.
 
If <var class="product">SirLib</var> does find a <code>BASE.<i>procname</i></code> procedure, it looks for the <code>CONTROL.<i>filename</i></code> procedure in the specified FixFile.
A control procedure of the specified name must exist or the <code>Q</code> prefix
command fails. Noting the active projects in the control procedure,
<var class="product">SirLib</var> finds all update procedure names that match this pattern:
<p class="code"><i>file.project.procname</i></p>
 
Where:
<ul>
<li><var class="term">file</var> is the name of the input file for this
operation. </li>
 
<li><var class="term">procname</var> is the name of the selected input
procedure. </li>
 
<li><var class="term">project</var> is one of the identifiers in
columns 1 to 8 of the specified control procedure. </li>
</ul>
 
All update procedure names that conform to this pattern are sorted by their
project and then by the sequence line numbers they effect.
This aggregate update is then applied to <code>BASE.<i>procname</i></code> to
produce the sequenced and unsequenced output procedures.
In other words, the programmer doesn't just get a copy of the procedure they
request, they get a generated procedure that is the BASE of what they
want, with all active updates applied.
 
If a project name is commented out in the control procedure, it is not
included in the resulting sequenced and unsequenced output procedures.
A project name is commented out by placing an asterisk (<tt>*</tt>) in
front of it in the control procedure. (This is how working versions of
production procedures can be generated in development regions if the
development region has active projects that do not exist yet in
production).
 
The sequenced version of a procedure should never be changed, as it is
the "before" image for the <code>XCOMPARE</code> that will eventually generate
the update procedure.
Sequence numbers generally should not concern programmers, though there are a few times when it is worth knowing something about how they work.
 
The <code>Q</code> prefix command automatically begins sequencing at 10000 and
increments each line in the <code>BASE.<i>procname</i></code> procedure by 10000.
As changes are generated, the <code>XCOMPARE</code> function generates new line numbers
for lines of code being inserted and replaced.
The <code>XCOMPARE</code> algorithm
attempts to number the first new line of code beginning with a sequence
number 1 greater than its starting point in the existing sequence (this
applies to Inserts and Replaces: it is irrelevant for Deletes).
Subsequent new lines which are part of the same update are incremented
by a power of 10 less than the last sequence of numbers for the section of code.
Later changes that apply to the same section again begin
numbering at their starting sequence number plus 1, and continue to
increment at the next lowest available power of 10.
 
Fortunately, you do not have to understand any of this in order for it to work.
The lower-order digit(s) of the sequence numbers
in a <code>SEQ</code> procedure however will indicate the number of times a section
of code has been changed. The sequence numbers themselves will
indicate whether the <code>XCOMPARE</code> will be able to "fit" changes into
the same section of code again.
For example, a section of code with sequence numbers that look like this indicates that changes will still "fit" in the hundreds and tens columns:
<p class="code">003451001
003452001
003453001
</p>
 
If an update procedure attempts to insert three lines of code
after line 003452001, the resulting code will be numbered like this:
<p class="code">003451001
003452001
003452102
003452202
003452302
003453001
003454001
</p>
Replace (a <code>./R</code> command in an update procedure) operates
slightly differently than Insert, but the outcome looks very similar.
When changes will no longer "fit," <code>XCOMPARE</code> can still
successfully generate an update procedure that effects this section of
code, but the update procedure will become unnecessarily long and
<var class="product">SirLib</var> might lose its ability to detect update collisions.
In this case, a Resequence is required. Resequencing is described later in this page.
 
Once an initial update has been coded and the update procedure placed
in the FixFile, all subsequent <code>Q</code> prefix commands against the same
procedure generate copies containing the update, and sequence
numbers in output sequenced versions of the procedure reflect the
insertion of the update code.
 
<div id="xcomp"></div>
==XCOMPARE: Creating an update procedure==
<!--Caution: <div> above-->
 
The <code>XCOMPARE</code> operation is executed by placing an <code>X</code> next to the
changed procedure on the Procedure List screen.
This invokes a compare operation of that procedure
against its sequenced version.
The output from this operation is an update procedure.
 
<p class="caption" style="margin-right:15em">XCOMPARE screen for creating a "differences" deck</p>
 
Prefixing a procedure by an X in the Procedure List screen
tells SirLib to compare the specified procedure against a matching
"sequenced" procedure, and to generate another procedure
containing the differences between the two.
The <code>X</code> prefix command presents the XCOMPARE screen, which has the following input fields:
 
<table class="thJustBold">
<tr><th nowrap>UnSequenced input procedure</th>
<td>Protected fields displaying the source file and procedure.</td></tr>
 
<tr><th>Sequenced input procedure</th>
<td>Source file of sequenced procedure. This defaults to the same file as for the input unsequenced procedure.</td></tr>
 
<tr><th>Password</th>
<td>Read access is required for the above file. No password need be input if the file is already open or has high enough default privileges to read procedures.</td></tr>
 
<tr><th>Procedure</th>
<td>Procedure name of sequenced procedure. <code>SEQ.</code> is the prefix generated by the <code>Q</code> command, so <code>XCOMPARE</code> defaults to this.</td></tr>
 
<tr><th>FixFile</th>
<td>Name of destination file for update procedure output from this <code>XCOMPARE</code>.</td></tr>
 
<tr><th>Password</th>
<td>Write access to this FixFile is required. If the file is already open, or if default privileges for the file are high enough to allow the creation of a new procedure, no password is required.</td></tr>
 
<tr><th>Project Name</th>
<td>This is the 8-character project name to which this update should be linked.
<p>
The <var class="product">SirLib</var> file administrator may have required that updates for this file only be linked to existing projects, in which case the entered project name is checked to make sure it exists in the control procedure. If this setting is not on, updates may be created, and the project entered in the control procedure later.</p></td></tr>
 
<tr><th>Target File</th>
<td>The production file containing the base procedure against which this update will apply.</td></tr>
 
<tr><th>Replace existing update?</th>
<td>Entering <code>Y</code> in this field lets you overwrite a same-named update procedure in the destination file with the current update procedure. Programmers are always permitted to overwrite update procedures created under their userid when this switch is set to <code>Y</code>.
<p>
The <var class="product">SirLib</var> file administrator may have specified in the Administration options that programmers may not overwrite each other's update procedures, either in this file or within the entire system. If this option is set, and an update procedure exists of the same name as the one being created in the target file, and the userid who created the update procedure (or last updated it) is not the same as the current user's ID, the generation of the update is not permitted.</p></td></tr>
 
<tr><th>Enter editor for update?</th>
<td>Entering <code>Y</code> at this prompt places the generating user into an edit session on the new update procedure. The update procedure will have already been stored before the edit session is invoked, so <b>QUIT</b> (PF3) may be used to exit the edit session without losing the update procedure.</td></tr>
 
<tr><th>Synchronization count</th>
<td>This field lets you set the number of lines that will be compared before the sequenced and unsequenced versions of the procedures are considered to be back in sync, and further lines are no longer to be generated to the output update procedure (at least until the next mismatch).
<p>
The default sync count value is 2, and this will work well for the vast majority of cases. Increasing the sync count may reduce the number of difference lines found,
resulting in smaller update procedures, or it may have no effect at all beyond a minor performance penalty in the <code>XCOMPARE</code> operation. In a very few cases it may produce larger output procedures. </p>
<p>
An entered value of asterisk (<code>*</code>) tells <code>XCOMPARE</code> to repeat the compare operation, increasing the sync count from 1 until it hits a value that no longer produces a smaller output procedure. As might be imagined, this is the worst-performing option for running <code>XCOMPARE</code>, but it will almost always generate the smallest possible output procedure. Unless changes are massive and many, the size of the output procedure is fairly irrelevant, and playing with the sync count has little utility.</p></td></tr>
 
<tr><th>Unlock this procedure?</th>
<td>Entering <code>Y</code> in this field makes the procedure available to other programmers in systems or files where procedures are locked to one updating user at a time.
<p>
Any value but <code>Y</code> lets you generate an update procedure, but it will retain the exclusive lock on the procedure (such as when a test integration is being run,
and you don't want to relinquish control of the procedures being updated). </p>
<p>
If procedure locking is not turned on, the lock/unlock information is still maintained for historical reporting, but this switch has no actual effect in locking procedures. See Administration options for Procedure Locking options.</p></td></tr>
</table>
 
<div id="newp"></div>
==New: Create a new procedure via update deck==
<!--Caution: <div> above-->
 
Prefixing a procedure by an <code>N</code> in the Procedure List screen
tells SirLib to generate an update procedure, similar to that produced by <code>X</code>,
but containing all lines of the specified procedure (because it is a new procedure to the system).
 
<p class="caption" style="margin-right:15em">Generating a "New" procedure</p>
 
Prefixing a procedure by <code>N</code> in the Procedure List screen
presents the Create New Proc screen, which has the following input fields:
 
<table class="thJustBold">
<tr><th>New procedure name</th>
<td>Protected fields displaying the source procedure file and source procedure for this update procedure creation.</td></tr>
 
<tr><th>Output update procedure</th>
<td>
<table class="thJustBold">
<tr><th>FixFile</th>
<td>The destination for the output update procedure.</td></tr>
 
<tr><th>Password</th>
<td>Write access to this FixFile file is required. If the file is already open, or if default privileges for the file are high enough to allow the creation of a new procedure, no password is needed.</td></tr>
 
<tr><th nowrap>Project name</th>
<td>A valid project identifier (up to 8-characters).
<p>The <var class="product">SirLib</var> file administrator may have required that updates for this file only be linked to projects previously defined in the control procedure. In this case the project entered is verified to see that it exists before the update is generated. If this setting is not on, updates may be generated first, and the project names entered in the control procedure later.</p></td></tr>
 
<tr><th>Target file</th>
<td>The name of the production file containing the base procedure to which this update will apply.</td></tr>
</table></td></tr>
 
<tr><th nowrap>Replace existing update?</th>
<td>Entering <code>Y</code> in this field lets you overwrite a same-named update procedure in the destination file with the current update procedure. Programmers are permitted to overwrite update procedures created under their userid when this switch is set to <code>Y</code>.
<p>
The <var class="product">SirLib</var> file administrator may have specified in the Administration options that programmers may not overwrite each other's update procedures either in this file or within the entire system. If this option is set, and an update procedure exists of the same name as the one being created in the target file, and the userid of the creator of the update procedure (or that last updated it) is not the same as the current user's ID, then the generation of the update procedure is not permitted.</p></td></tr>
 
<tr><th>Enter Editor for update?</th>
<td>Entering <code>Y</code> at this prompt places the generating user into an edit session on the new update procedure. The update procedure will have already been stored before the edit session is invoked, so <b>QUIT</b> may be used to exit the edit session without the update procedure being lost.</td></tr>
</table>
 
<div id="klobber"></div>
==K (Klobber): Managed-update procedure deletion==
<!--Caution: <div> above-->
 
Prefixing a procedure by a <code>K</code> in the Procedure List screen
generates an update procedure that contains only a special command that tells <var class="product">SirLib</var> that the "change" to the K-prefixed procedure is a delete.
Managed update deletes are always logical deletes, allowing deleted procedures to be recovered at any time when the file is reconfigured.
For this reason, an empty (zero-line) version of the erased procedure is left in the file and should not be physically deleted.
 
The <code>K</code> prefix command presents the
<b>Klobber procedure</b> screen, which has the same input fields as the <b>Create New proc</b> screen described in [[#newp|New: Create a new procedure via update deck]].
 
<p class="caption" style="margin-right:15em">"K" (klobber) Generating a logical procedure deletion</p>
 
<div id="reseqnc"></div>
==ReSequence: Refreshing internal sequence numbers==
<!--Caution: <div> above-->
 
The sequence numbers generated by <var class="product">SirLib</var> are generally of no concern to the programmers working on procedures.
However, if a large number of update procedures are generated that affect the same section
of code in a procedure, further changes to the same section may result
in unnecessarily large update procedures.
In addition, <var class="product">SirLib</var> will
lose its ability to detect when updates are overwriting each other.
 
In case this rare event occurs, a manager can generate a resequence procedure.
By placing a <code>Z</code> in front of the procedure name on the Procedure List screen,
the <b>ReSequence procedure</b> screen is produced:
 
<p class="caption" style="margin-right:15em">Z: Resequencing a managed procedure</p>
 
The <b>ReSequence procedure</b> screen has the following input fields:
<table class="thJustBold">
<tr><th>Resequence procedure</th>
<td>
<table class="thJustBold">
<tr><th>Proc file
<br/>Procedure</th>
<td>These are protected fields displaying the source file and procedure name for this update procedure creation.</td></tr>
</table></td></tr>
 
<tr><th>Output update procedure</th>
<td>
<table class="thJustBold">
<tr><th><tr><th>FixFile</th>
<td>Destination for output update procedure.</td></tr>
 
<tr><th>Password</th>
<td>Write access to this FixFile file is required. If the file is already open, or if default privileges for the file are high enough to allow the creation of a new procedure, no password is needed.</td></tr>
 
<tr><th nowrap>Project name</th>
<td>A valid project identifier (as many as 8 characters).
<p>
The <var class="product">SirLib</var> file administrator may have required that updates for this file be linked only to projects previously defined in the control procedure.
In this case, the project entered is verified to see that it exists before the update is generated. If this setting is not on, updates may be generated first, and the project names entered in the control procedure later.</p></td></tr>
 
<tr><th>Target file</th>
<td>The name of the production file containing the base procedure to which this update will apply.</td></tr>
</table></td></tr>
 
<tr><th nowrap>Replace existing update?</th>
<td>Entering <code>Y</code> in this field lets you overwrite a same-named update procedure in the destination file with the current update procedure.
Programmers are permitted to overwrite update procedures created under their userid when this switch is set to <code>Y</code>.
<p>
The <var class="product">SirLib</var> file administrator may have specified in the Administration options that programmers may not overwrite each other's update procedures either in this file or within the entire system. If this option is set, and an update procedure exists of the same name as the one being created in the target file, and the userid that created the update procedure (or last updated it) is not the same as the current user's, the generation of the update procedure is not permitted.</p></td></tr>
 
<tr><th>Enter editor for update?</th>
<td>Entering <code>Y</code> at this prompt places the generating user into an edit session on the new update procedure. The update procedure is already stored before the edit session is invoked, so <b>QUIT</b> may be used to exit the edit session without the update procedure being lost.</td></tr>
</table>


==SirPro change management overview==
==SirPro change management overview==
Line 397: Line 62:


Notice that no sequenced copy of a procedure is needed for New, Erase,
Notice that no sequenced copy of a procedure is needed for New, Erase,
or Resequence operations. <code>Q</code> (seQuence) is the managed update equivalent of a Copy, just as <code>N</code> (New) is the equivalent of Create, and <code>K</code>
or Resequence operations. <var>Q</var> (seQuence) is the managed update equivalent of a Copy, just as <var>N</var> (New) is the equivalent of Create, and <var>K</var> (Klobber, or Erase) is the equivalent of Delete.
(Klobber, or Erase) is the equivalent of Delete.
<var>XCompare</var> has no direct equivalent in the "unmanaged" command structure, though coupled with later reconfiguration using the output update procedure, it is analogous to moving finished changes to a staging area. Resequencing is of course a special purpose function with no "unmanaged" corollary.
<code>XCOMPARE</code> has no direct equivalent in the "unmanaged" command structure, though coupled with later reconfiguration using the output update procedure, it
is analogous to moving finished changes to a staging area.
Resequencing is of course a special purpose function with no "unmanaged" corollary.


<p class="caption" style="width:444px">How a change progresses through SirLib</p>
<p class="figure">[[File:SirLibChange.png|444px]]</p>
<p class="figure">[[File:SirLibChange.png|444px]]</p>
<p class="caption" style="margin-right:15em">How a change progresses through SirLib</p>


In the example above, procedure <code>TEMP</code> exists in file <code>PFILE1</code> (upper left). The programmer uses the <code>Q</code> command to copy <code>TEMP</code> into <code>WORKFILE</code>, getting both a working and a <code>SEQ</code> version of the procedure.  
In the example above, procedure <code>TEMP</code> exists in file <code>PFILE1</code> (upper left). The programmer uses the <code>Q</code> command to copy <code>TEMP</code> into <code>WORKFILE</code>, getting both a working and a <code>SEQ</code> version of the procedure.  
Line 410: Line 72:
A single line of new code is inserted in <code>TEMP</code> (the line
A single line of new code is inserted in <code>TEMP</code> (the line
<code>PRINT STATE AND ZIP AT 40</code>).
<code>PRINT STATE AND ZIP AT 40</code>).
Using <code>XCOMPARE</code>, the update is generated to file <code>CHANGES</code>, and named <code>PFILE1.CHG1.TEMP</code>.
Using <var>XCompare</var>, the update is generated to file <code>CHANGES</code>, and named <code>PFILE1.CHG1.TEMP</code>.
A project leader defines the project name <code>CHG1</code> in code>CONTROL.PFILE1</code>.
A project leader defines the project name <code>CHG1</code> in <code>CONTROL.PFILE1</code>.


Finally, <var class="product">SirLib</var>'s ReConfiguration function is used to create a "BASE" version of the procedure, so the update can be backed out if necessary, and the original procedure <code>TEMP</code> is deleted.
Finally, <var class="product">SirLib</var>'s ReConfiguration function is used to create a "BASE" version of the procedure, so the update can be backed out if necessary, and the original procedure <code>TEMP</code> is deleted.

Latest revision as of 00:45, 22 June 2017

Overview

Managed-update commands allow the manipulation and promotion of just the updates you make to a procedure, "deltas," instead of preserving and working with a sequence of updated copies of the entire procedure or entire procedure file. Managed-update commands are available in SirPro if the change management system, SirLib, is active in the Online.

Note: Managed-update commands are not available in RKWeb; they require the SirPro TN3270 interface.

The output from a managed-update command that produces update procedures contains a single-line comment describing the creator, date, time, and source file for the change.

The managed-update commands are entered as prefix commands on the procedure list screen (see SirPro procedure-list operations). These prefix commands are:

X XCompare.

Compares two versions of a procedure and creates a third procedure containing the differences between the two. This output is an "update procedure," the physical unit managed by the change management system.

Q Sequence.

Creates both a working and sequenced version of a procedure that are the later input to XCompare.

N New.

Creates a "differences" update procedure similar to XCompare, but which is the source for a new procedure.

K Erase.

Creates an update procedure similar to XCompare output, but telling SirLib to perform a logical delete on the procedure.

Z ReSequence.

Creates a special update procedure to reorder the internal sequence numbers of a procedure.

U Undo.

Like Q, but may only be executed against a change deck. It adds the change deck to the code for the working procedure, but not to the code from the sequenced copy. Added in version 7.5.

Y Refresh.

Refreshes your local working copy of a procedure with changes that have been checked in by other programmers since the working copy was originally taken from the source procedure file. Added in version 7.5.

The Procedure List screen is the main working environment for the programmer in the SirPro/SirLib-controlled environment. This screen, and others like it, provide access to all procedure activity in Model 204. For details on the use of SirLib, including the special commands for managed updates, see SirLib. Only the special Procedure List screen prefix commands (Q, X, K, N, Z, U, and Y) for creating and manipulating managed updates are explained here.

The Q, X, N, K, Z, U, and Y prefix commands are used to generate "working" base and sequenced copies of procedures and to generate updates from those copies. Type one of these managed update commands to the left of the selected procedure, and press the Enter key. SirPro then presents one of the managed update screens to get further details on the managed update. Those screens are shown in the following detailed sections.

Q (Sequence): Create working copies of procedures

"Sequencing" is the managed update method by which programmers make copies of procedures to work on. In other systems, programmers make backup copies of procedures and then work on the original. In SirPro, programmers never alter the original program code: they execute Q commands to get working and sequenced copies from which update procedures can be generated.

Updates must be done in a file other than the original, which is why procedure groups are recommended for development subsystems.

SirPro screen for generating SEQ and working procedure copies

The Q command tells SirLib to generate both a copy of the selected procedure (the copy that the programmer will work on) and a "sequenced" copy of the procedure (a copy containing sequence or line numbers), which will later be used as comparison input for the XCompare command. Building these copies is always the first programming step in generating a managed update.

The Q prefix command presents a screen (Sequence procedure) with the following input fields:

Input procedure The following two fields identify the source procedure, that is, the version of the procedure before it is changed. This information is copied from the entry on the SirPro procedure editor screen.
Proc file Name of the Model 204 file containing the source procedure.
Procedure Name of the source procedure. This is the procedure that was subject to a Q prefix command on the SirPro Edit screen.
Output procedures SirLib is designed to work in a Model 204 subsystem (APSY) context using procedure groups.

The Q command creates two output procedures that must be in a different file from the source procedure. One of these procedures is used as a working copy, while the other procedure is used to determine any changes made to the working copy. Both of these procedures are formed by applying any staged updates to the indentified source procedure.

Proc file Name of the Model 204 file to contain the two procedures produced by the SirLib Q command.
Password If a password is required for update access to the file it must be entered here.
Unsequenced procedure Name of the procedure that will become the working copy for developing and testing changes. This defaults to the name of the source procedure.
Sequenced procedure Name of the procedure that will contain a sequenced version (each line prefixed by a sequence number) of the working copy, before any changes have been made. The sequenced procedure may be used by the X command (see next section) to prepare an update procedure reflecting any changes made to the working copy.

The default procedure name for sequenced procedures is the unsequenced procedure name prefixed with SEQ.:

SEQ.unsequenced-procedure-name

This default prefix may be overridden if it conflicts with local conventions.
Location of control and
update procedures
SirLib uses a naming convention to identify any updates that should be applied to the source procedure before generating a working copy.

The FixFile is searched for a "control procedure" whose name must be the name of the input procedure file prefixed with CONTROL.:

CONTROL.input-procedure-proc-file-name

The control procedure identifies all projects with updates to procedures in the input procedure file. For each such project, the FixFile is checked for update procedures that should be applied to the source procedure.

FixFile Name of Model 204 file containing control and update procedures used to build the output procedures. The default file is SIRLIBP.
Password Read access is required for the control procedure and update procedures. If a password is required for read access, it must be entered here.
Replace existing procedures? Overlaying a working copy or sequenced copy of a procedure can cause updates in progress to be lost. The default for this field is N, which directs the Q command to not overwrite an existing procedure. If you want to overwrite existing procedures, set this indicator to Y.

Q command processing

This section's content provides a deeper understanding of how the command works; although knowing the processing details is not a requirement to use the product.

When the Q command is executed, SirLib looks in the source file for a procedure named BASE.procname, where procname is the name of the selected procedure. If no such procedure is found, SirLib copies the procedure into the target procedure in the Output file. In addition, SirLib generates a sequenced copy of the procedure, named whatever the programmer specified in the Sequenced Procedure field on this screen. The sequenced copy of the procedure is identical to the unsequenced (or working) copy, except that each line is prefixed with a sequence number.

If SirLib does find a BASE.procname procedure, it looks for the CONTROL.filename procedure in the specified FixFile. A control procedure of the specified name must exist, or the Q command fails. Noting the active projects in the control procedure, SirLib finds all update procedure names that match the pattern:

file.project.procname

Where:

  • file is the name of the input file for this operation.
  • procname is the name of the selected input procedure.
  • project is one of the identifiers in columns 1 to 8 of the control procedure.

All update procedure names that conform to this pattern are sorted by their project, then by the sequence line numbers they affect. This aggregate update is then applied to BASE.procname to produce the sequenced and unsequenced output procedures. In other words, the programmer doesn't just get a copy of the procedure they request, they get a generated procedure composed of the Base procedure with all updates applied to it.

If a project name is commented out in the control procedure, it is not included in the resulting sequenced and unsequenced output procedures. A Project name is commented out by placing an asterisk (*) in front of it in the control procedure. (This is how working versions of production procedures can be generated in development regions if the development region has active projects that do not exist yet in production).

The sequenced version of a procedure should never be changed, as it is the "before" image for the XCompare that will eventually generate the update procedure.

Understanding the sequence numbers

Sequence numbers should not concern programmers for the most part, though there are a few times when it is worth knowing something about how they work.

The Q command automatically begins sequencing at 10000, and it increments each line in the BASE.procname procedure by 10000. As changes are generated, the XCompare function generates new line numbers for lines of code being inserted and replaced. The XCompare algorithm attempts to number the first new line of code beginning with a sequence number 1 greater than its starting point in the existing sequence (this applies to Inserts and Replaces: it is irrelevant for Deletes).

Subsequent new lines that are part of the same update are incremented by a power of 10 less than the last sequence of numbers for the section of code. Later changes that apply to the same section again begin numbering at their starting sequence number plus 1, and they continue to increment at the next lowest available power of 10.

The lower-order digit(s) of the sequence numbers in a SEQ procedure indicate the number of times a section of code has been changed. The sequence numbers themselves indicate whether the XCompare is able to "fit" changes into the same section of code again. For example, a section of code with sequence numbers like the following indicates that changes still "fit" in the hundreds and tens columns:

003451001 003452001 003453001

If an update procedure attempts to insert three lines of code after line 003452001, the resulting code is numbered like this:

003451001 003452001 003452102 003452202 003452302 003453001 003454001

Replace (./R) commands operate slightly differently than Insert, but the outcome looks very similar. If changes no longer "fit" within the sequence numbers, XCompare still generates an update procedure for this section of code, but the update procedure is unnecessarily long, and SirLib might lose its ability to detect update collisions. In this case, a Resequence is required, as described later in this page.

Once an initial update is coded and the update procedure saved in the FixFile, all subsequent Q commands against the same procedure generate copies containing the update, and sequence numbers in output sequenced versions of the procedure reflect the insertion of the update code.

X (XCompare): Create an update procedure

Prefixing a procedure by an X in the SirPro procedure list tells the SirLib system to compare the specified procedure against a matching "sequenced" procedure, generating an update procedure that contains the differences between the two.

The X prefix command presents an XCompare screen:

SirPro XCompare screen

Unsequenced input procedure Identifies the procedure to be examined for changes; it was the object of an X command from a SirPro procedure list screen.
Proc file Protected field showing name of input procedure.
Procedure Protected field showing name of unsequenced input procedure.
Sequenced input procedure Identifies the sequenced version of the input procedure, showing its contents prior to any changes.
Proc file Name of Model 204 file containing the sequenced input procedure. Deafults to the same file as the input unsequenced procedure.
Password Read access is required for the sequenced input procedure. If the file is not already open with sufficient privileges and a password will be required, enter it here.
Procedure Name of the procedure containing a sequenced representation of the unsequenced input procedure before any changes were applied. Defaults to the name of the unsequenced input procedure with a prefix of SEQ..
Output update procedure Identifies the location and name of an update procedure that will contain the changes that have been made to the sequenced version of the source procedure.
FixFile Name of Model 204 file to contain the update procedure produced by this invocation of XCompare.
Password Write access is required for the output update procedure. If the file is not already open with sufficient privileges and a password will be required, it should be entered here.
Project name This is the 8-character project name to which this update should be linked.

The file administrator may have required that updates for this file only be linked to existing projects, in which case the entered project name is checked to make sure it exists in the control procedure. If this setting is not on, updates may be created, and the project entered in the control procedure later.

Target File This is the production file containing the base procedure against which this update will apply.
Replace existing update Entering Y in this field allows the user to overwrite an existing version of the update procedure with the latest changes.

Programmers are always permitted to overwrite update procedures created under their userid when this switch is set to Y. The file administrator may have specified in the Administration options that programmers may not overwrite each other's update procedures either in this file or within the entire system.

If this option is set on, an update procedure exists of the same name as the one being created in the target file, and the ID of the user who created the update procedure (or last updated it) is not the same as the current user's ID, the generation of the update is not permitted.

Enter Editor for update Entering Y in this prompt places the generating user into an edit session on the new update procedure. The update procedure will have already been stored before the edit session is invoked, so PF3 or Quit may be used to exit the edit session without losing the update procedure.
Synchronization count This field allows programmers to set the number of lines that are compared before:
  1. The sequenced and unsequenced versions of the procedures are considered to be back in sync.
  2. Further lines are no longer to be generated to the output update procedure (at least until the next mismatch).

The default sync count value is 2, which works well for the vast majority of cases.

Increasing the sync count may reduce the number of difference lines found, resulting in smaller update procedures, or it may have no effect at all beyond a minor performance penalty in the XCompare operation. In a very few cases it may produce larger output procedures.

An entered value of * tells XCompare to repeat the compare operation, increasing the sync count from 1 until it reaches a value that no longer produces a smaller output procedure. This is the worst-performing option for running XCompare, but it almost always generates the smallest possible output procedure. Unless changes are massive and many, the size of the output procedure is fairly irrelevant, and adjusting the sync count has little utility.

Unlock this procedure? Entering Y in this field makes the procedure available to other programmers in systems or files where procedures are locked to one updating user at a time.

Any value but Y lets you generate an update procedure but retain the exclusive lock on the procedure (such as when a test integration is being run, and you don't want to relinquish control of the procedures being updated). If procedure locking is not turned on, the lock/unlock information is still maintained for historical reporting, but this switch has no actual effect in locking procedures. For more information about procedure locking, see View/Clear procedure locks.

N (New): Create a new procedure from update deck

Preceding an N to the left of a procedure name in the SirPro procedure list screen tells the system to generate an update procedure, similar to that produced by X, but containing all lines of the specified procedure (because it is a new procedure to the system). The N prefix command presents a Create New proc screen:

Generating a new update procedure

New procedure name Identifies the new procedure, which was the object of an N command from a SirPro procedure list screen.
Proc file Name of Model 204 file containing the new procedure.
Procedure Name of the new procedure.
Output update procedure Identifies the location and name of the new update procedure.
FixFile Name of Model 204 file to contain the update procedure.
Password Write access is required for the output update procedure. If the file is not already open with sufficient privileges and a password is required, enter it here.
Project name The 8-character project name to which this update should be linked.

The file administrator may have required that updates for this file only be linked to projects previously defined in the control procedure.

In this case the project entered is verified to see that it exists before the update is generated. Otherwise the project name is used to determine the name for the update procedure.

Target file The name of the production file that contains the base procedure against which this update will apply.
Replace existing update Entering Y in this field lets you overwrite an existing version of the update procedure with the latest changes.

Programmers are always permitted to overwrite update procedures created under their user ID if this switch is set to Y.

The file administrator may have specified in the Administration options that programmers may not overwrite each other's update procedures in this file or within the entire system. If this option is set, and an update procedure exists of the same name as the one being created in the target file, and the ID of the user who created the update procedure (or last updated it) is not the same as the current user's ID, the generation of the update is not permitted.

Enter Editor for update Entering Y in this prompt places the generating user into an edit session on the new update procedure. The update procedure will have already been stored before the edit session is invoked, so PF3 or Quit may be used to exit the edit session without losing the update procedure.

K (Klobber): Generate a logical procedure deletion

Placing a K to the left of a procedure name in the SirPro procedure list screen directs SirLib to generate an update procedure that will cause the deletion of the indicated procedure.

Note: Managed update deletes are always logical deletes, allowing deleted procedures to be recovered at any time when the file is reconfigured. For this reason, an empty (zero-line) version of the deleted procedure is left in the file, and it should not be physically deleted.

The K prefix command presents a Klobber procedure screen:

Generating a logical delete of a procedure in SirPro

Procedure to erase Identifies the procedure to be erased, which was the object of a K prefix command from a SirPro procedure list screen.
Proc file Name of Model 204 file containing the procedure.
Procedure Name of procedure to be deleted.
Output update procedure Identifies the location and name of an update procedure that will represent deletion of the procedure.
FixFile Name of Model 204 file to contain the update procedure.
Password Write access is required for the output update procedure. If the file is not already open with sufficient privileges and a password is required, enter it here.
Project name This is the 8-character project name to which this update should be linked. The file administrator may have required that updates for this file only be linked to projects previously defined in the control procedure. In this case the project entered is verified to see that it exists before the update is generated. Otherwise, the project name is used to determine the name for the update procedure.
Target File This is the production file containing the base procedure against which this update will apply.
Replace existing update Entering Y in this field allows the user to overwrite an existing version of the update procedure with the latest changes.

Programmers are always permitted to overwrite update procedures created under their userid when this switch is set to Y.

The file administrator may have specified in the Administration options that programmers may not overwrite each other's update procedures, either in this file or within the entire system. If this option is set, and an update procedure exists of the same name as the one being created in the target file, and the ID of the user who created the update procedure (or last updated it) is not the same as the current user's ID, the generation of the update is not permitted.

Enter Editor for update Entering Y in this prompt places the generating user into an edit session on the new update procedure. The update procedure will have already been stored before the edit session is invoked, so PF3 or Quit may be used to exit the edit session without losing the update procedure.

Z (Resequence): Refresh internal sequence numbers

The sequence numbers generated by SirLib are for the most part of no concern to SOUL programmers. However, if a large number of update procedures are generated that effect the same areas of code in a procedure, further changes to the same areas may result in unnecessarily large update procedures. In addition, the process of untangling overlapping updates with SirLib will become more complex and possibly compromised.

In case this rare event occurs, a manager need only generate a resequence procedure. By placing a Z to the left of the procedure name on the SirPro procedure list screen, the Resequence procedure screen is invoked:

Resequencing a procedure in SirPro

Resequence procedure Identifies the procedure to be resequenced; it was the object of the Z prefix command on the SirPro procedure list screen.
Proc file Name of Model 204 file containing the procedure.
Procedure Name of procedure.
Output update procedure Identifies the location and name of an update procedure that will contain the resequencing of the procedure.
FixFile Name of Model 204 file to contain the update procedure.
Password Write access is required for the output update procedure. If the file is not already open with sufficient privileges and a password will be required, it should be entered here.
Project name The 8-character project name to which this update should be linked. The file administrator may have required that updates for this file only be linked to projects previously defined in the control procedure. In this case, the project entered is verified to see that it exists before the update is generated. Otherwise the project name is used to determine the name for the update procedure.
Target file The production file containing the base procedure against which this update will apply.
New starting number The default is to begin renumbering with 10000.
New increment The default is to renumber in increments of 10000.
Replace existing update Entering Y in this field allows the user to overwrite an existing version of the update procedure with the latest changes.

Programmers are always permitted to overwrite update procedures created under their user ID if this switch is set to Y.

The file administrator may have specified in the Administration options that programmers may not overwrite each other's update procedures either in this file or within the entire system. If this option is set, and an update procedure exists of the same name as the one being created in the target file, and the ID of the user who created the update procedure (or last updated it) is not the same as the current user's ID, the generation of the update is not permitted.

Enter Editor for update Entering Y in this prompt places the generating user into an edit session on the new update procedure. The update procedure will have already been stored before the edit session is invoked, so PF3 or Quit may be used to exit the edit session without losing the update procedure.

U (Undo): Recover from a mistake

The U command performs the same operation as Q, but it may only be executed against a change deck. It results in a "working" procedure and a sequenced copy of that procedure being created in the user's selected development procedure file. However, the U command specifically includes the change deck against which it is executed in the code for the working procedure, but not in the code from the sequenced copy. In other words, it recreates the state of the development procedures that created the change deck against which the U command is executed.

Typically, the U command is used to recreate the state of development if you accidentally delete the procedures you were working on, either manually, or with the "Clean-up" switch on the Xcompare screen.

The control screen you are presented with after specifyng a U command is like the following. For information about the screen's fields, see the Q command fields above:

Recreating a working procedure

The U command is a special-use feature, and there are a number of ways in which it fails to work: most notably, if the selected change deck is somewhere in the middle of a series of changes, and by excluding it from procedure creation, some code dependency is missing. However, for its primary function — recovering from a mistake that was made very recently, typically as the most recent change to a procedure — it should always work.

Y (Refresh): Apply post-check-out updates

The Y command provides a special check-out ability in which you can "refresh" your local working copy of a procedure with changes that have been checked in by other programmers since your working copy was originally taken from the source procedure file.

When Y is applied against a working procedure (in the screen that contains the list of working copies of procedures), you are presented with a screen like the following:

Refreshing a working procedure

After the screen is processed, the result is both of these:

  • A new working procedure with all checked-in updates applied and your current changes still in place
  • A sequenced copy that has all updates applied, but your current changes not in place

In other words, the Y command is very much like a Q command, but it is done while changes are in progress, and it puts into place other changes that have occurred since the original procedure check-out.

When you subsequently check in your changes to the file, your resulting change deck will include only your changes, but correctly integrated with the other programmers' changes.

The following input fields are available on the Refresh procedure screen:

(Input procedure)
Proc file
This non-editable field should display the original source file for the procedure (probably not the file that contained the working copy).
(Input procedure)
Procedure
This non-editable field is the name of the procedure to be refreshed.
(Output procedure)
Proc file
This is the destination file for the sequenced and unsequenced copies.
Password Password for the output procedure file. A blank should suffice here since the file is probably already open.
Unsequenced procedure Generally this is the same as the name of the input procedure.
Sequenced procedure This defaults to, and it is recommended to be left as, the name of the input procedure with a prefix of SEQ..
FixFile Enter the name of the file that contains the update procedures and the control procedure for the file being updated.

If the CONTROL.filename procedure is not found in the specified FixFile, SirPro cannot build the copies of the procedure. An error message is posted, and processing ceases.

SirPro change management overview

Notice that no sequenced copy of a procedure is needed for New, Erase, or Resequence operations. Q (seQuence) is the managed update equivalent of a Copy, just as N (New) is the equivalent of Create, and K (Klobber, or Erase) is the equivalent of Delete. XCompare has no direct equivalent in the "unmanaged" command structure, though coupled with later reconfiguration using the output update procedure, it is analogous to moving finished changes to a staging area. Resequencing is of course a special purpose function with no "unmanaged" corollary.

How a change progresses through SirLib

In the example above, procedure TEMP exists in file PFILE1 (upper left). The programmer uses the Q command to copy TEMP into WORKFILE, getting both a working and a SEQ version of the procedure.

A single line of new code is inserted in TEMP (the line PRINT STATE AND ZIP AT 40). Using XCompare, the update is generated to file CHANGES, and named PFILE1.CHG1.TEMP. A project leader defines the project name CHG1 in CONTROL.PFILE1.

Finally, SirLib's ReConfiguration function is used to create a "BASE" version of the procedure, so the update can be backed out if necessary, and the original procedure TEMP is deleted. The update procedure PFILE1.CHG1.TEMP is applied to BASE.TEMP to create the new executable procedure TEMP.

The final state of PFILE1 is shown lower right.

See also