SirLib problem resolution

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

SirLib can't access file

Make sure that each file managed by SirLib is allocated via SUBSYSMGMT to the SIRLIB application subsystem, or that an update password exists for the file.

Cutover failed

Cutover is a complex function involving 5 steps:

1. Apply updates.
2. Delete update procedures.
3. Delete project names.
4. Delete Base procedures.
5. ReStamp procedures.

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 SirLib 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 SirLib 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 SirLib ASPY definition, or run SirLib in TEST DEBUG mode, and call the specific problem in to your SirLib Administrator or to 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, SirLib 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, SirLib assumes this is the first time managed updates have been applied to the procedure, and a new BASE. 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 Q command. The SEQ. version created must remain unchanged while the unsequenced (working) copy is being updated. If the SEQ. version is altered, the update procedure resulting from the XCOMPARE will not apply correctly to the BASE procedure, and the entire reconfiguration will fail.

If an SEQ. procedure is deleted or is suspected of being altered, the programmer needs to generate a new SEQ. version via the following steps:

1. Verify that no unmanaged changes have occurred against the procedure since the working version was generated.
2. If managed changes have occurred against the procedure since the original sequenced version was generated, comment them out in the CONTROL procedure via the CHANGES option in SirLib and regenerate a new SEQ version that includes those changes, by executing a Q command.
3. Regenerate the sequenced and unsequenced procedures from the original using the Q command, sending the unsequenced version to a temp file, which can be deleted.

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. SirLib 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, SirLib 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 SirLib 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 SirLib, and the second change contains commands that try to find sequence numbers that are now altered by the first change.

When SirLib applies update procedures to BASE procedures, it sorts all changes for a procedure into sequence and version number order. If SirLib 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 SirLib 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 Q command to generate SEQ 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 SEQ and working procedures to include the production fix.

See also

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