View source for Template:SirPro commands

==<b id="sequenc"></b>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 <var class="product">SirPro</var>, programmers never alter the original program code: they execute <var>Q</var> 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.
 
<p class="caption" style="width:450px">SirPro screen for generating SEQ and working procedure copies</p>
<p class="figure">[[File:SlibSeqProc.png|450px]]</p>
 
The <var>Q</var> command tells <var class="product">SirLib</var> 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 <var>XCompare</var> command.
Building these copies is always the first programming step in generating
a managed update.

The <var>Q</var> prefix command presents a screen (<b>Sequence procedure</b>) with the following input fields:
<table class="thJustBold">
<tr><th>Input procedure</th>
<td>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.
<table class="thJustBold" id="Qfields">
<tr><th>Proc file</th>
<td>Name of the <var class="product">Model 204</var> file containing the source procedure.</td></tr>
 
<tr><th>Procedure</th>
<td>Name of the source procedure. This is the procedure that was subject to a <var>Q</var> prefix command on the <var class="product">SirPro</var> Edit screen.</td></tr>
</table></td></tr>
 
<tr><th>Output procedures</th>
<td><var class="product">SirLib</var> is designed to work in a <var class="product">Model 204</var> subsystem (APSY) context using procedure groups.
The <var>Q</var> 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.
 
<table class="thJustBold">
<tr><th>Proc file</th>
<td>Name of the <var class="product">Model 204</var> file to contain the two procedures produced by the <var class="product">SirLib</var> <var>Q</var> command.</td></tr>
 
<tr><th>Password</th>
<td>If a password is required for update access to the file it must be entered here.</td></tr>
 
<tr><th>Unsequenced procedure</th>
<td>Name of the procedure that will become the working copy for developing and testing changes. This defaults to the name of the source procedure.</td></tr>
 
<tr><th>Sequenced procedure</th>
<td>Name of the procedure that will contain a sequenced version (each line prefixed by a sequence number) of the working copy, <b>before</b> any changes have been made. The sequenced procedure may be used by the <var>X</var> command (see next section) to prepare an update procedure reflecting any changes made to the working copy.
<p>
The default procedure name for sequenced procedures is the unsequenced procedure name prefixed with <code>SEQ.</code>: </p>
<p class="code">SEQ.<i>unsequenced-procedure-name</i></p>
This default prefix may be overridden if it conflicts with local conventions.</td></tr>
</table></td></tr>
 
<tr><th>Location of control and <br>update procedures</th>
<td><var class="product">SirLib</var> 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 <code>CONTROL.</code>:
<p class="code">CONTROL.<i>input-procedure-proc-file-name</i></p>
<p>
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.  </p>

<table class="thJustBold">
<tr><th>FixFile</th>
<td>Name of <var class="product">Model 204</var> file containing control and update procedures used to build the output procedures. The default file is <code>SIRLIBP</code>.</td></tr>
 
<tr><th>Password</th>
<td>Read access is required for the control procedure and update procedures. If a password is required for read access, it must be entered here.</td></tr>
</table></td></tr>
 
<tr><th nowrap>Replace existing procedures?</th>
<td>Overlaying a working copy or sequenced copy of a procedure can cause updates in progress to be lost.
The default for this field is <code>N</code>, which directs the <var>Q</var> command to not overwrite an existing procedure. If you want to overwrite existing procedures, set this indicator to <code>Y</code>.</td></tr>
</table>
 
===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 <var>Q</var> command is executed, <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 procedure into the
target procedure in the 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 <var>Q</var> command fails. Noting the active projects in the control procedure, <var class="product">SirLib</var> finds all update procedure names that match the pattern:
<p class="code"><i>file</i>.<i>project</i>.<i>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 control procedure.</li>
</ul>
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 <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 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 (<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 <var>XCompare</var> 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 <var>Q</var> command automatically begins sequencing at 10000, and it 
increments each line in the <code>BASE.<i>procname</i></code> procedure by 10000. As changes are generated, the <var>XCompare</var> function generates new line numbers for lines of code being inserted and replaced.
The <var>XCompare</var> 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 <var>SEQ</var> procedure indicate the number of times a section of code has been changed. The sequence numbers themselves indicate whether the <var>XCompare</var> 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:
<p class="code"><nowiki>003451001
003452001
003453001
</nowiki></p>
If an update procedure attempts to insert three lines of code
after line <code>003452001</code>, the resulting code is numbered like this:
<p class="code"><nowiki>003451001
003452001
003452102
003452202
003452302
003453001
003454001
</nowiki></p>
 
Replace (<code>./R</code>) commands operate slightly differently than
Insert, but the outcome looks very similar.
If changes no longer "fit" within the sequence numbers, <var>XCompare</var> still generates an update procedure for this section of code, but the update procedure is unnecessarily long, and <var class="product">SirLib</var> 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 <var>Q</var> 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.
 
==<b id="xcomp"></b>X (XCompare): Create an update procedure==
Prefixing a procedure by an <var>X</var> in the <var class="product">SirPro</var> procedure list tells the <var class="product">SirLib</var> system to compare the specified procedure against a matching "sequenced" procedure, generating an update procedure that contains the differences between the two. 

The <var>X</var> prefix command presents an <var>XCompare</var> screen:
 
<p class="caption" style="width:450px">SirPro XCompare screen</p>
<p class="figure">[[File:SlibXcompare.png|450px]]</p>
 
<table class="thJustBold">
<tr><th nowrap>Unsequenced input procedure</th>
<td>Identifies the procedure to be examined for changes; it was the object of an <var>X</var> command from a <var class="product">SirPro</var> procedure list screen.
<table class="thJustBold">
<tr><th>Proc file</th>
<td>Protected field showing name of input procedure.</td></tr>
 
<tr><th>Procedure</th>
<td>Protected field showing name of unsequenced input procedure.</td></tr>
</table></td></tr>
 
<tr><th>Sequenced input procedure</th>
<td>Identifies the sequenced version of the input procedure, showing its contents prior to any changes. 
<table class="thJustBold">
<tr><th>Proc file</th>
<td>Name of <var class="product">Model&nbsp;204</var> file containing the sequenced input procedure. Deafults to the same file as the input unsequenced procedure.</td></tr>
 
<tr><th>Password</th>
<td>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.</td></tr>
 
<tr><th>Procedure</th>
<td>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
<code>SEQ.</code>.</td></tr>
</table></td></tr>
 
<tr><th nowrap>Output update procedure</th>
<td>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.
 
<table class="thJustBold">
<tr><th>FixFile</th>
<td>Name of <var class="product">Model 204</var> file to contain the update procedure produced by this invocation of <var>XCompare</var>.</td></tr>
 
<tr><th>Password</th>
<td>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.</td></tr>
 
<tr><th nowrap>Project name</th>
<td>This is the 8-character project name to which this update should be linked.
<p>
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.</p></td></tr>
 
<tr><th>Target File</th>
<td>This is the production file containing the base procedure against which this update will apply.</td></tr>
</table></td></tr>
 
<tr><th>Replace existing update</th>
<td>Entering <code>Y</code> 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 <code>Y</code>.
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.
<p>
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.</p></td></tr>
 
<tr><th nowrap>Enter Editor for update</th>
<td>Entering <code>Y</code> 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.</td></tr>
 
<tr><th>Synchronization count</th>
<td>This field allows programmers to set the number of lines that are compared before:
<ol>
<li>The sequenced and unsequenced versions of the procedures are considered to be back in sync. </li>

<li>Further lines are no longer to be generated to the output update procedure (at least until the next mismatch). </li>
</ol>
<p>
The default sync count value is 2, which works well for the vast majority of cases. </p>
<p>
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 <var>XCompare</var> operation. In a very few cases it may produce larger output procedures.</p>
<p>
An entered value of <code>*</code> tells <var>XCompare</var> 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 <var>XCompare</var>, 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.</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 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 [[SirLib change control#View/Clear procedure locks|View/Clear procedure locks]].</p></td></tr>
</table>
 
==<b id="newp"></b>N (New): Create a new procedure from update deck==
Preceding an <var>N</var> to the left of a procedure name in the <var class="product">SirPro</var> procedure list screen tells the
system to generate an update procedure, similar to that produced by <var>X</var>, but containing <i>all</i> lines of the specified procedure (because it is a new procedure to the system). 
The <var>N</var> prefix command presents a <b>Create New proc</b> screen:
 
<p class="caption" style="width:450px">Generating a new update procedure</p>
<p class="figure">[[File:SlibCreateNew.png|450px]]</p>
 
<table class="thJustBold">
<tr><th>New procedure name</th>
<td>Identifies the new procedure, which was the object of an <var>N</var> command from a <var class="product">SirPro</var> procedure list screen.
 
<table class="thJustBold">
<tr><th>Proc file</th>
<td>Name of <var class="product">Model&nbsp;204</var> file containing the new procedure.</td></tr>
 
<tr><th>Procedure</th>
<td>Name of the new procedure.</td></tr>
</table></td></tr>
 
<tr><th nowrap>Output update procedure</th>
<td>Identifies the location and name of the new update procedure.
<table class="thJustBold">
<tr><th>FixFile</th>
<td>Name of <var class="product">Model&nbsp;204</var> file to contain the update procedure.</td></tr>
 
<tr><th>Password</th>
<td>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.</td></tr>
 
<tr><th nowrap>Project name</th>
<td>The 8-character project name to which this update should be linked. <p>
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.</p></td></tr>
 
<tr><th>Target file</th>
<td>The name of the production file that contains the base procedure against which this update will apply.</td></tr>
</table></td></tr>
 
<tr><th>Replace existing update</th>
<td>Entering <code>Y</code> 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 <code>Y</code>.
<p>
The file administrator may have specified in the [[SirLib change control#Administering system and file profiles|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.</p></td></tr>
 
<tr><th nowrap>Enter Editor for update</th>
<td>Entering <code>Y</code> 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.</td></tr>
</table>
 
==<b id="klobber"></b>K (Klobber): Generate a logical procedure deletion==
Placing a <var>K</var> to the left of a procedure name in the <var class="product">SirPro</var> procedure list screen directs <var class="product">SirLib</var> to generate an update procedure that
will cause the deletion of the indicated procedure.
<p class="note"><b>Note:</b> 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. </p>
<p>
The <var>K</var> prefix command presents a <b>Klobber procedure</b> screen: </p>
 
<p class="caption" style="width:450px">Generating a logical delete of a procedure in SirPro</p>
<p class="figure">[[File:SlibKlobber.png|450px]]</p>
 
<table class="thJustBold">
<tr><th>Procedure to erase</th>
<td>Identifies the procedure to be erased, which was the object of a <var>K</var> prefix command from a <var class="product">SirPro</var> procedure list screen.
 
<table class="thJustBold">
<tr><th>Proc file</th>
<td>Name of <var class="product">Model 204</var> file containing the procedure.</td></tr>
 
<tr><th>Procedure</th>
<td>Name of procedure to be deleted.</td></tr>
</table></td></tr>
 
<tr><th nowrap>Output update procedure</th>
<td>Identifies the location and name of an update procedure that will represent deletion of the procedure.
 
<table class="thJustBold">
<tr><th>FixFile</th>
<td>Name of <var class="product">Model 204</var> file to contain the update procedure.</td></tr>
 
<tr><th>Password</th>
<td>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.</td></tr>
 
<tr><th nowrap>Project name</th>
<td>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.</td></tr>
 
<tr><th>Target File</th>
<td>This is the production file containing the base procedure against which this update will apply.</td></tr>
</table></td></tr>
 
<tr><th>Replace existing update</th>
<td>Entering <var>Y</var> 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 <var>Y</var>.
<p>
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.</p></td></tr>
 
<tr><th nowrap>Enter Editor for update</th>
<td>Entering <var>Y</var> 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.</td></tr>
</table>
 
==<b id="reseqnc"></b>Z (Resequence): Refresh internal sequence numbers==
The sequence numbers generated by <var class="product">SirLib</var> 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
<var class="product">SirLib</var> will become more complex and possibly compromised.
<p>In case this rare event occurs, a manager need only generate a resequence procedure. By placing a <var>Z</var> to the left of the procedure name on the SirPro procedure list screen, the <b>Resequence procedure</b> screen is invoked: </p>
 
<p class="caption" style="width:450px">Resequencing a procedure in SirPro</p>
<p class="figure">[[File:SlibResequence.png|450px]]</p>
 
<table class="thJustBold">
<tr><th>Resequence procedure</th>
<td>Identifies the procedure to be resequenced; it was the object of the <var>Z</var> prefix command on the <var class="product">SirPro</var> procedure list screen.
 
<table class="thJustBold">
<tr><th>Proc file</th>
<td>Name of <var class="product">Model 204</var> file containing the procedure.</td></tr>
 
<tr><th>Procedure</th>
<td>Name of procedure.</td></tr>
</table></td></tr>
 
<tr><th nowrap>Output update procedure</th>
<td>Identifies the location and name of an update procedure that will contain the resequencing of the procedure.
 
<table class="thJustBold">
<tr><th>FixFile</th>
<td>Name of <var class="product">Model 204</var> file to contain the update procedure.</td></tr>
 
<tr><th>Password</th>
<td>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.</td></tr>
 
<tr><th nowrap>Project name</th>
<td>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.</td></tr>
 
<tr><th>Target file</th>
<td>The production file containing the base procedure against which this update will apply.</td></tr>
</table></td></tr>
 
<tr><th>New starting number</th>
<td>The default is to begin renumbering with 10000.</td></tr>
 
<tr><th>New increment</th>
<td>The default is to renumber in increments of 10000.</td></tr>
 
<tr><th>Replace existing update</th>
<td>Entering <code>Y</code> 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 <code>Y</code>.
<p>
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.</p></td></tr>
 
<tr><th nowrap>Enter Editor for update</th>
<td>Entering <code>Y</code> 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.</td></tr>
</table>

==U (Undo): Recover from a mistake==
The <var>U</var> command performs the same operation as <var>Q</var>, 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 <var>U</var> command specifically includes the change deck against which it is executed in the code for the working procedure, but <b>not</b> 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 <var>U</var> command is executed.

Typically, the <var>U</var> 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 <var>Xcompare</var> screen.

The control screen you are presented with after specifyng a <var>U</var> command is like the following. For information about the screen's fields, see the [[#Qfields|Q command fields]] above:

<p class="caption" style="width:450px">Recreating a working procedure</p>
<p class="figure">[[File:SProUcmd.png|450px]]</p>

The <var>U</var> 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 &mdash;
recovering from a mistake that was made very recently, typically
as the most recent change to a procedure &mdash; it should always work.

==Y (Refresh): Apply post-check-out updates==
The <var>Y</var> 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 the working copy was originally taken from
the source procedure file. 

When <var>Y</var> is applied against a working procedure, you are presented with a screen like the following:

<p class="caption" style="width:450px">Refreshing a working procedure</p>
<p class="figure">[[File:SProYcmd.png|450px]]</p>

The result is both of these:
<ul>
<li>A new working procedure with all updates applied <b>and</b> your current changes still in place </li>

<li>A sequenced copy that has all updates applied, but your current changes not in place </li>
</ul>

In other words, the <var>Y</var> command is very much like a <var>Q</var> 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.