JAL: minor cleanup

2015-10-28T00:08:05Z

minor cleanup

Admin: 1 revision

2015-10-19T21:37:24Z

1 revision

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

JAL at 23:18, 16 October 2015

2015-10-16T23:18:03Z

New page

This page reviews corrective actions for a variety of common error conditions.

==SirLib can't access file==
Make sure that each file managed by <var class="product">SirLib</var> is allocated via SUBSYSMGMT to the <code>SIRLIB</code> application subsystem, or that an update password exists for the file.

==Cutover failed==
Cutover is a complex function involving 5 steps:
<ol>
<li>Apply updates. </li>
<li>Delete update procedures. </li>
<li>Delete project names. </li>
<li>Delete Base procedures. </li>
<li>ReStamp procedures. </li>
</ol>
Only the first and last options may be bypassed.
Each of the five options is executed in the above order.
If a step fails it can be identified by the error message and by the
date/time fields associated with it not having been updated when control
returns to the Cutover screen.

The first step applies update procedures to the target managed file.
This process is exactly the activity performed from the Reconfiguration
option, and may be bypassed if the user has just run a Reconfiguration.
If the first step is executed (recommended always)
and fails, then the destination procedure file does not have
all existing changes applied to it.

This change application process does not apply changes which
are commented-out in the control procedure, and it cannot know if all
update procedures that are supposed to be in the FixFile are indeed there.
Most of the error messages occurring at this step will indicate that some
user or apsy is locking a procedure that <var class="product">SirLib</var> wants to update.

See the ReConfiguration section for details on this.

Each of the remaining four steps is an updating transaction requiring
update privileges to the update procedure file or the target
procedure file.

===Troubleshooting===
The first thing to check in case of cutover failure is that these files
are allocated to the online region and to the <var class="product">SirLib</var> APSY, and that privilege settings are high enough to allow the updating of permanent procedures.

If cutover continues to fail, either turn on all messages in the <var class="product">SirLib</var> ASPY definition, or run <var class="product">SirLib</var> in <var>TEST DEBUG</var> mode, and call the
specific problem in to your <var class="product">SirLib</var> Administrator or to [[Contacting Rocket Software Technical Support|Technical Support]].

Cutover may be run as many times as necessary to accomplish the file clean up.

==Missing base procedure==
If a Base procedure of a file once existed and has since been deleted,
<var class="product">SirLib</var> will see there is no Base, copy the existing executable
procedure into a Base version and then attempt to apply changes to it.
The user will get an error saying that changes (from the first update
procedure most likely) will not apply to the procedure.
The error message will specify the sequence number where the problem occurred.
The user will be able to edit both the procedure and the update
procedure and see that the new code in the update procedure being
applied already exists in the Base procedure.

A Base version of a procedure is created the first time a change to the
procedure is detected during a reconfiguration.
If a Base procedure is not present when a re-configuration is attempted,
<var class="product">SirLib</var> assumes this is the first time managed updates have been applied
to the procedure, and a new <code>BASE.</code> procedure is created.

The Base procedure is more important to a managed system than the
actual executable procedure.
Base procedures with update procedures applied are used to rebuild the
executable procedures to any previous configuration.

If a BAase procedure is accidentally deleted while there are still
changes that need to be applied to that procedure, the Base procedure
must be restored for those changes to apply.
Each Base procedure must be in the same file as the executable procedure
that it matches.

==Missing SEQ procedure==
Sequenced versions of procedures are generated during execution of the
<var>Q</var> command.
The <var>SEQ.</var> version created must remain unchanged while the
unsequenced (working) copy is being updated.
If the <var>SEQ.</var> version is altered, the update procedure resulting from the
<var>XCOMPARE</var> will not apply correctly to the BASE procedure, and the entire
reconfiguration will fail.

If an <var>SEQ.</var> procedure is deleted or is suspected of being altered, the
programmer needs to generate a new <var>SEQ.</var> version via the following steps:
<ol>
<li>Verify that no unmanaged changes have occurred against the procedure
since the working version was generated.</li>

<li>If managed changes have occurred against the procedure since the
original sequenced version was generated, comment them
out in the <code>CONTROL</code> procedure via the CHANGES option in <var class="product">SirLib</var> and
regenerate a new <var>SEQ</var> version that includes those changes, by executing a <var>Q</var> command.</li>

<li>Regenerate the sequenced and unsequenced procedures from the
original using the <var>Q</var> command, sending the unsequenced version to a temp file, which can be deleted.</li>
</ol>

==Deleted update procedure==
Update procedures can be regenerated as many times as required, as long
as the original sequenced and unsequenced versions of the procedure
still exist.

==Reconfiguration failed==
Usually Reconfiguration failures are due to an APSY or USER holding the
target file open.
Reconfiguration requires exclusive access to the target file.
<var class="product">SirLib</var> does not check that a specific APSY is locking a file, as it
makes no assumptions about how many APSYs might be running out of that file.
Therefore, <var class="product">SirLib</var> always presents this error upon its inability to
delete or rename some procedure.
Reconfiguration can be restarted when the locking USER or APSY releases
the file.

If an invalid update procedure has been built and reconfiguration
fails, a message is displayed indicating the update procedure at fault
and the sequence number where the mismatch occurred.
Reconfiguration will also fail in the case where two or more
programmers have attempted to change the same line number from working
and SEQ procedures generated at the same time.
In <var class="product">SirLib</var> this is known as a "collision".

==Collisions==
Update collisions occur during ReConfiguration when two update
procedures attempt to change the same line or section of a procedure,
both referring to the same physical location in the procedure by the
same sequence number(s).
This can occur when more than one programmer generates sequenced and
unsequenced copies of the same procedure in a time frame that doesn't
allow the second programmer's copy to include changes from the first
programmer's update procedure.

Read the section under the Q command for an explanation of how sequence numbering works.

In the case of collisions, the first change gets applied by <var class="product">SirLib</var>, and
the second change contains commands that try to find sequence numbers
that are now altered by the first change.

When <var class="product">SirLib</var> applies update procedures to BASE procedures, it sorts all
changes for a procedure into sequence and version number order.
If <var class="product">SirLib</var> finds within a section of code two changes that both want to be
the same version it warns the user and stops processing.

There are many ways to handle collisions and the best is usually
determined by the programmers.
A simple approach is to delete all but the most complex of the conflicting
update procedures and to incorporate the other changes into the working
version of the procedure that was used to generate the one update
procedure kept.
That update procedure is then regenerated.
In some cases the working and SEQ version of the most complex update
procedure will have been deleted.
In this case it is best to regenerate the conflicting update procedure
using an SEQ procedure that contains the other change(s).

To avoid difficult resolution of collisions, working and SEQ procedures
should never be deleted until the programmer has verified that the
changes apply and integrate with all other changes.

==Production fixes==
Sometimes it will be necessary to make a quick change to a production
procedure which has already been updated in development.
In <var class="product">SirLib</var> developers should never copy production procedures back to
development in order to make these fixes.

In the production environment identify which changes have been applied
to the procedure which requires the fix.
This can be done by browsing the procedure to see the change stamps, or if
procedure stamping is turned off for the target procedure, by running a
status report for the file to identify the last Reconfigure date and time,
and the projects which were then applied.

In the development environment, ReConfigure the file to its current
production state.
Execute a <var>Q</var> command to generate <var>SEQ</var> and working versions of the procedure.
Make the production fix, generate an update procedure and distribute the
new update procedure to production, applying the update procedure there
via a ReConfigure.

In the development environment, ReConfigure the file to include the new
fix and all other new development update procedures.
Handle collisions as indicated earlier in this section.
Notify all developers working on the fixed procedure to regenerate their
<var>SEQ</var> and working procedures to include the production fix.

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

[[Category: SirLib]]

SirLib problem resolution - Revision history

JAL: minor cleanup

Admin: 1 revision

JAL at 23:18, 16 October 2015