SirLib change control
SirLib functions are accessed through a main menu in the SirLib subsystem
(Selection 2 from the UL/SPF screen).
The main menu also allows specification of a File and FixFile.
The File field specifies the procedure file targeted for the requested activity.
The FixFile field specifies the Model 204 procedure file that contains the
CONTROL.filename procedure and all update procedures for the
selected File.
SirLib Main Menu
Options 1, 2 and 5 require a File to be input.
If FixFile is not specified for Option 1, 2, or 5, the default
FixFile value as defined in the Administration option will be used.
If FixFile is specified for these options, the specified FixFile value
overrides the default.
This allows, for instance, files to be reconfigured from different sets of update procedures in different FixFiles.
SirLib's default FixFile is always SIRLIBP.
Change Management functions are:
| 1. Project Definitions | Add, delete or change the Project identifiers in the FixFile assigned to a managed file. |
|---|---|
| 2. Configure | Apply and backout changes to files (that is; change the configuration of the file). |
| 3. Administration | Administration functions define system defaults and file-specific overrides for those defaults, for security, procedure stamping, Administration ID assignment and other "profile" options. This function is also used to remove files from the SirLib system. |
| 4. Security | Defines access to SirLib main menu options and to the Resequence command (Z) in SirPro.
Security settings only apply if SECURE is set to Y in the Administration function for the file (or for the system, if the file is not specifically set). |
| 5. Cutover | Does a large-scale clean-up of BASE. Procedures, update procedures, Project identifiers and internal procedure stamps. This option is used infrequently; perhaps between major releases of an application. |
| 6. Reports | Access to SirLib reports. |
| 7. View/Clear Procedure Locks | Access to a display screen of all procedures (optionally restricted by file) that are currently checked out. The "checked out" procedures are displayed even if the administration option for multiple updates is turned on, and therefore no procedures are really locked. |
Project definition
SirLib is a file-based system. It is not specifically aware of the subsystem structure of a site's applications. This allows SirLib to manage applications that have a single procfile-to-subsystem relationship for all their subsystems, as well as those that run many subsystems from a single file or have multiple procedure files per subsystem.
SirLib uses two pieces of information to track updates and
configuration status for a file.
One way is via a single FILE record, kept in SIRLIBD, which holds security and
administrative information for the file.
The other is the file's Control procedure which is stored with the file's
update procedures in a FixFile.
Control procedures are named CONTROL.filename>, where
filename is the name of the managed file.
Control procedures contain a single line for each Project name.
A Project is a logical change.
Update procedures are linked to projects by naming convention.
Update procedures are named:
filename.project.procname
The first qualifier tells SirLib what file the update applies to. The second qualifier indicates the project to which the update is linked. The third qualifier is the procedure to be changed.
The project name qualifier provides a mechanism for grouping changes, and controlling and linking their application and backout. When a project is added to a Control procedure, the whole set of changes linked to that project becomes included in any reconfiguration of that file. If the project is commented out or deleted, all update procedures whose names contain that project name are "backed out;" that is, not applied to the Base procedure(s) during the next reconfiguration.
Control procedures may be edited directly in the Model 204 editor by users who have been given access to the FixFile (FixFiles should be private files). However, the format of the lines of the procedure must be carefully maintained. Each line of the CONTROL procedure must have a Project identifier in column 1-8 (left-justified and blanks to the right if shorter than eight characters). Column 9 must be blank and columns 10 through 72 may contain a comment. The Project Identifier must be in uppercase. The optional comment may be in mixed case. If a Project name begins with an asterisk (*), SirLib considers the entire line a comment. Updates are backed out by commenting-out project names in this way, and reconfiguring a file. SirLib skips the commented line, applying all previous and subsequent updates.
The proper way to maintain Projects is via Option 1 in SirLib. This screen allows users to add, change and delete Project identifiers. It verifies the format of the Project identifier, automatically converting it to uppercase. To access this screen, a file must be specified on the main menu: Project identifiers are always file-specific, as are the Control procedures in which they are contained. If a project spans more than one file, an identifying line for that project must be placed in the control procedure for each file to which the project applies.
While adding, deleting, changing and commenting out project identifier are all simple tasks, the user should keep in mind that these identifiers are control nodes for applying and backing out whole sets of updates. Simple actions taken on these nodes can have major consequences. Of particular importance are the following issues:
- Order
Updates are applied in the order shown in the Control procedure. A project, being the name of a logical change, may point to many update procedures (physical changes).
If the order of project names is altered in the control procedure, and update procedures across projects affect the same section of the same procedure, the sequence numbers in later updates may not match those in the existing procedure, and the attempt to reconfigure the file will fail. In this case the ReConfigure option in SirLib will tell the user the update procedure that failed to apply and the sequence number where the error occurred.
- Logical Dependency
There is no way SirLib or any other change management system can know about logical dependencies between source code changes in different update procedures. A %variable declared in one update may be used by code built by another update procedure. Backing out the first change may allow the second to apply correctly (that is, all the lines of code physically verify before they are applied). But the resulting program may not function correctly because the declaration of the %variable is missing from the resulting procedure.
It is important that physical changes which are logically dependent upon on another be applied and backed out together, and this is done by linking them to the same project.
From the Project Definition screen, PF2 gives access to an edit session
in which the user may add as much documentation as required to the project.
The user edits into a procedure in mixed-case mode, and when the edit session is
exited, the lines of the procedure are converted to TEXT fields in SIRLIBD, and
linked to the appropriate Project Identifier.
Configuring files (applying updates)
Applying updates is always done one file at a time. The process is called ReConfiguring a file. The file and FixFile are selected on the SirLib main menu at the time Option 2 is selected. The SirLib File Reconfiguration screen is then displayed:
SirLib File Reconfiguration
SCREEN ID=LIBR07.Applying Fixes/Changes
The above screen shows how the programmer applies changes to a file.
Pressing Enter while on this screen applies all active updates in the
FixFile to the Base version of target procedures in the target file.
This option may be protected by the System Administrator, so that only
approved users may reconfigure a file.
If a procedure is locked when SirLib attempts to apply changes to it, the ReConfiguration fails and a message is displayed identifying the procedure that could not be updated by SirLib. This could happen if a user is editing the procedure, or if the procedure is locked by an active application subsystem. The ReConfiguration should be done over again. ReConfiguration may be run as many times as needed, until all changes are properly applied. When a ReConfiguration fails in this manner the file may be left in a state where some procedures are deleted. The faulty update should be fixed or commented out and reconfiguration run again.
Backing out changes
ReConfiguration ignores all projects that are prefixed by an asterisk (*). The manager who wishes to backout all updates linked to a project, can do so by commenting out the project name in the Project screen, and reconfiguring the file using option 2. This takes only a few minutes of work and is independent of DUMP/RESTORE or other external backups of the file. To backout only one or some of several updates associated with a project, the manager may delete the update procedure or change its name so it is no longer found when SirLib checks for updates linked to projects. Deleting update procedures is a severe remedy in any case and should be avoided, as the source working procedure from which the update was generated may no longer exist.
Each active Project in the Control procedure must be linked to at least one update, or the ReConfiguration will fail. If updates are deleted or renamed such that none link to a particular project, the project name should also be commented out or deleted.
Applying updates in batch mode
Updates can also be applied in batch mode. The command for applying fixes in batch mode is:
SIRLIB BATCH target-filename fixfile-name [source-filename]
Where:
- target-filename is the file to be reconfigured, that is, needs updating.
- fixfile-name is the file that contains the update procedures.
- source-filename is optional and allows fixes originally written
against one procedure file to be applied to a different file.
This is useful if the source procedure file in the development environment has a different name than the procedure file in production. In the standard case, where the target and source procedure files are the same or have the same name, this parameter can either be left blank or can be the same as the target file.
The following command:
SIRLIB BATCH SIRMON SIRFIXES SIRMON
results in the same changes being applied to subsystem SIRMON as:
SIRLIB BATCH SIRMON SIRFIXES
The following example shows changes, originally written against DEVPPROC
being applied to PRODPROC (with the change decks coming from SIRLIBD):
SIRLIB BATCH PRODPROC SIRLIBD DEVPROC
This command does not have to be placed in a batch job: it can be typed directly in at Model 204 command level, or it can be inserted in the User 0 stream, or invoked in an IODEV3 thread.
One use of the batch SirLib command is to place the command for each managed file in the User 0 stream of the production Online. This allows application updates to be "staged" to production by copying them to the production FixFile, with the application update occuring automatically each time the online comes up.
To aid in batch debugging and job control, SIRLIB also sets a global SIRLIBFAILURE to 0 if the configuration command worked correctly, and to 1 if the command failed. This global can be used to set JOBCODEs or to initiate recovery steps in the event the batch configuration fails. A message detailing the reason for the configuration failure is printed to CCAPRINT.
Administering system and file profiles
:SCREEN ID=LIBR30.SirLib Administration screen
- SD L=01 C=01 BRIGHT. ------------------- * * * SIRLIB Administration * * * --------------------
The SirLib Administration Option allows users to define a custom SirLib profile for each file. If the Administration option is selected with no file specified on the main menu, then the System Profile is being defined or changed. If a File value is specified on the main menu, then a file-specific profile is being defined or changed.
Only users defined to the ADMIN SCLASS in the SirLib subsystem definition are allowed access to the Administration option without specifying a file. Only users defined as Administrators in the System profile are allowed access to File profiles.
The settings on the SirLib Administration screen are described below. If any of these settings is left blank on a File profile, SirLib takes its behavior from the System profile setting. If the option is left blank on the System profile, default action varies, but is noted in the descriptions below.
| File | A file name is displayed only if one was specified on the main menu. The file name cannot be modified on the Administration screen. If no file was specified on the main menu, then this field will read System Defaults. |
|---|---|
| Changes File | A Changes File (FixFile) is a Model 204 procedure file that contains update procedures and a CONTROL.filename procedure for a file or set of files. Any number of files may share the same FixFile.
The default FixFile for all of SirLib is SIRLIBP, a Model 204 procedure file that was created as part of the SirLib installation process. If a different FixFile is specified as the default for a managed file, SirLib options 1, 2, 5, and all SirLib reports will look in the new FixFile for update procedures and the control procedure. |
| Single Checkout | This switch affects the behavior of the Q command in SirPro.
The default, Once a procedure is checked out by a programmer, it may not be checked out by another via a managed update command until the previous programmer signals that it is available by checking it back in. The checkout occurs automatically when a Q command is executed. The checkin is optional on the X screen, when the final update procedure is being generated. The programmer simply checks Y at the bottom of the Xcompare screen to unlock the procedure. Users in the SirLib ADMIN sclass can view and remove procedure locks by Option 7 from the SirLib main menu. Regardless of the setting of this switch, SirLib stores a lock record for each procedure that is the subject of a Q (Sequence) command. This allows managers to view a list of procedures being updated even when the procedure is not actually locked. |
| Overwrite protection | This switch affects the behavior of the SirPro X prefix command.
By default SirPro allows users to overwrite each others' update procedures, provided a switch is checked on the Xcompare panel when generating the second update procedure. The Overwrite switch on the Administration screen never stops programmers from overwriting their own changes. However if Overwrite is set toN on this panel, SirLib will not allow a programmer to replace an update procedure generated by another user. |
| Require Project Identifiers | The system default is to allow programmers to generate update procedures for any project, whether or not the project name is listed in the CONTROL.filename procedure for the file.
If this toggle is set to filename.project.proc-name The project qualifier in the above naming convention is the value that is checked when this option is set to Requiring project names to exist before updates are linked to them allows the manager to specify destinations for update procedures, and may prevent changes from being left out of a release by inadvertent misspellings of project names by programmers. The advantage of not requiring a project name to exist before changes are linked to it is that it provides a "control point" to switch on an entire project. That is, update procedures may be generated to FixFiles over a period of time, but they don't get included in file reconfigurations until a project name is entered, and at that point they are all made active simultaneously. |
| Keep History | Setting this switch to N reduces the amount of historical information kept by SirLib. Certain history records are maintained regardless of this setting, such as ReConfigurations and Cutovers. |
| Secure | This option globally turns on and off SirLib internal security, for the system as a whole or for a particular file.
If this switch is set to
If on the default System profile, Secure is |
| Administrator IDs | Administrator IDs defined for the System profile (i.e. when no file is specified on entering the Administration Option) are given access to Administration functions for all files.
These System Administrators may then access Administration options to set File profiles. Users defined as Administrators for a File have access to Security (Option 5) for the files they administer. Up to 12 IDs may be specified as Administrators for the system and for each file. If a shop wishes to use SirLib and SirPro on an honor system basis, one of the simplest ways to do it is to define all users to the ADMIN SCLASS of SirLib, and either turn security off, or let each user build whatever permissions they require for themselves or their development group. |
| Procedure Stamping | This switch indicates whether or not a comment is inserted in a changed procedure. The comment indicates the name, date, time, and source file of the change.
Procedure Stamping may be set on or off globally (Y to turn stamping on, N to turn it off) on the Administrator setup screen. Internal procedure stamps can be deleted by SirLib when the file is "Cutover" (refer to Release cutover). The deleted stamps may be replaced with comment stamps indicating the cutover date, time, and administrator ID. Default SirLib behavior is to stamp procedures.
|
| Exempt Prefixes | If procedure stamping is "on," a list of procedure prefixes may be entered for procedures in the system or for a file which should not have comments inserted.
This prevents SirLib comments from entering procedures that contain application help text, message text or other literal information used by the application.
Prefixes for exempt procedures may be up to 32 characters long. Wild card characters such as |
Files are added to the SirLib system via the Administration screen. For a file to participate in Managed update activity, it must have at least a file name entered on this screen, and the entering user must have pressed ??.
To remove a file from the SirLib system, press PF10, and SirLib will remove all security, history, procedure locks, administration, and user privileges for the file. If the file has already been added to the SirLib subsystem, use SUBSYSMGMT to remove it.
Release cutover
One way to use SirLib is to keep update procedures forever, allowing unlimited flexibility to reconfigure a system to a previous state. However, as systems age it may be inconvenient to keep applying a large number of projects and even larger number of update procedures. The "cutover" option essentially returns a managed file to a pre-managed state, but with all existing updates applied.
Cutovers always occur on a file-by-file basis. Performing a cutover causes the following SirLib processing:
- ReConfiguration
Cutover invokes a full file ReConfiguration to ensure that all updates are applied. This step can be bypassed with a switch on the Cutover screen.
- Delete Update procedures
All update procedures in the FixFile that have the cutover file as a first qualifier are deleted whether or not they are linked to an active project.
- Delete Project Identifiers
All lines in the control procedure for the file (CONTROL.<cutover-file>) are deleted.
- Delete Base Procedures
All procedures beginning with
BASE.are deleted from the target cutover file. - Delete Comments
When changes have been applied, SirLib will have inserted a comment like the following at the beginning of each changed procedure:
*** F2BALES Applied by ... ***
These comments are deleted at cutover, and a single new comment reading as follows is inserted (procedures excluded from inserted commenting are not stamped; see System Setup):
*** Cutover on DD/MM/YY
The re-stamping of procedures with a Cutover stamp can be suppressed by a switch on the Cutover screen.
Cutover is initiated from the SirLib main menu using option 5. The file to be cutover is specified on the main menu along with the FixFile from which the changes are to be applied and deleted. If the FixFile field is left blank, the default FixFile from the File record is used.
SCREEN ID=LIBR15.Cutover Information Display * * * SIRLIB File Cutover * * *
A scrollable panel at the bottom of the Cutover screen lets you view the changes that are to be applied. If the projects shown are not the ones you want applied and deleted, the process should not be continued until the appropriate FixFile is located.
The remaining fields on the Cutover screen display information to help the file manager determine the state of the file and changes associated with the file. Existing projects are displayed in a block at the bottom of the screen. Dates and times are displayed for the first SirLib transaction for this file, the first and last reconfiguration, and the most recent cutover. All of this information is refreshed after a successful cutover.
From the Cutover panel, PF12 initiates the cutover. If the cutover fails during any step a failure message appears when the screen is refreshed, and the user should check the date and time stamps for each activity to see which step failed. Refer to SirLib problem resolution for advice on error recovery.
Because the results of a cutover are irreversible it is recommended that cutovers always be prefaced by a backup of the managed file and its associated FixFile. It is also recommended that the Reconfiguration step not be bypassed unless the user knows for certain that a reconfiguration has just been run. Care should be taken to verify that changes are not incorrectly "commented out" in the Control procedure. If any step fails to execute properly, processing stops at that step and control is returned to the Cutover panel, where an error message is displayed. After cutover compleyes, the date stamps for each activity will be updated on the Cutover panel. The user should verify these dates and times before exiting.
View/Clear procedure locks
Procedures have a record posted whenever a programmer takes a
managed update copy of the procedure using the Q command.
This record becomes a lock when the manager has set Single User Update to Y in the Administration screen.
Programmers unlock procedures by executing an X (Xcompare) against
the locked procedure, specifying Y in the field on the Xcompare
screen that asks whether the procedure should be unlocked.
The View/Clear locks option in SirLib is a way for managers to track and
modify procedure locking.
View/Clear Procedure Locks
Access to this option is determined by ADMIN SCLASS membership.
To clear a lock, place an S to the left of the procedure name. Locks are cleared when the Enter key is pressed. If you specified a file name on the SirLib main menu when invoking the View/Clear Procedure Locks function, only those procedures locked from the specified file are displayed.
The list may be scrolled and sorted with the displayed PF keys.
In the View/Clear locks option, the procedure name is displayed to a maximum length of 33 characters. Following that, the display shows the programmer owning the procedure, the source file for the checkout, the workfile and the date and time the checkout occurred. PF12 allows the view to be toggled into a fullname mode, in which long procedure names overlay the user and file information on the right side of the screen.