SirLib change control

SirLib main menu

SirLib functions are accessed through its main menu (the Configuration and Change Control System screen) in the SIRLIB subsystem. This screen is displayed by selecting item 2 from the RKTools System Main Menu screen.

In RKWeb, this screen is accessed by selecting Build > Configure, and Janus Web Legacy Support provides a facsimile of the TN3270 screen.

SirLib main menu

The SirLib main menu also lets you specify a Target file and a Fixes File. The Target file field specifies the procedure file targeted for the requested activity. The Fixes File field specifies the Model 204 procedure file that contains the CONTROL.filename procedure and all update procedures for the selected file.

Main menu options 1, 2, and 5 require a file specification: If Fixes File is not specified and you select option 1, 2, or 5, the default Fix File value defined in the SIRLIB Administration screen (main menu option 3) is used. If Fixes File is specified for these options, the specified Fixes File 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.

Main menu options are described briefly in the following table and in depth in the sections that follow on this page. In addition to these options, you can also use this or any of the SirPro screen's fast path commands and online Help (F1 function key). Pressing F1 while the cursor is located on a screen field invokes the Help text for that field; otherwise, the Help text is positioned at the start of the Help for the screen.

Main menu option descriptions

1. Project Definition List	Add, delete, or change the project identifiers in the FixFile assigned to a managed file.
2. Apply changes (Reconfigure a file)	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 SIRLIB Administration screen 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.

Control and update procedures

SirLib uses two pieces of information to track updates and configuration status for a file. One is 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.

Editing a control procedure

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 through Option 1 in the SirLib main menu. The resulting screen lets you 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 identifiers are all simple tasks, 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 Apply changes (ReConfigure a file) option in SirLib tells you 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 that 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 you may add as much documentation as required to the project. You edit in mixed-case mode. When you exit the edit session, the lines of the edit procedure are converted to TEXT fields in SIRLIBD, and they are 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.

You invoke a reconfiguration by specifying the target file and the fix file on the SirLib main menu, then selecting Option 2, Apply changes (Reconfigure a file). This produces a screen like the following (which results from target file M204PROC and fix file M204FIX):

SirLib file reconfiguration

Applying Fixes/Changes

You use the SirLib File ReConfiguration screen to apply changes to a file. Pressing Enter while on the 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.

If 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 should be run again.

Backing out changes

Reconfiguration ignores all projects that are prefixed by an asterisk (*). To backout all updates linked to a project, you comment out the project name in the Project definition screen, then reconfigure the file using option 2. This takes only a few minutes of work, and it 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, you 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 it 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 fails.

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 occurring 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

SIRLIB Administration

The SirLib Administration option lets you define a custom SirLib profile for each file. If you select the SirLib main menu Administration option with no target file specified, then the system profile is being defined or changed. If a Target 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 function 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 SIRLIB Administration screen. If no file was specified on the main menu, then this field will read Defaults.
Fix File	A 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 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, N, allows multiple programmers to update the same procedure at the same time, and leaves it up to SirLib to handle possible collisions when the update procedures are applied. The administrator may switch this option to Y to force a "checkout" to occur when the Q command is executed against a procedure. 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 check-in 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 subsystem user class (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 screen 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 to N on this screen, SirLib does not allow a programmer to replace an update procedure generated by another user.
Require Change 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 Y, programmers may only name their update procedures using project names that exist in the control procedure. Note: The format of update procedure names is: filename.project.procname The project qualifier in the above naming convention is the value that is checked when this option is set to Y. Requiring project names to exist before updates are linked to them allows the manager to specify destinations for update procedures, and it 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 N the only security in effect is determined by users' SCLASS privileges from SUBSYSMGMT. ADMIN SCLASS users only are permitted access to the Administration and View/Clear Procedure Locks options from the main menu. All other options are available to any user with access to the SirLib subsystem. If Secure is set to Y, SirLib will pay attention to the values set by administrators in the Secure option. If on the default System profile, Secure is N, specific files that require security can override this setting by specifying Y for Secure on their administration screen. The reverse can also be done, with the system set to use security by default, and files that need no such detailed coverage set with security off. A blank setting for Secure on a file record tells SirLib to use the System Defaults for that file. If Secure is left blank in the system profile, SirLib assumes it should be N.
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. Note: When working versions of procedures are generated (via the Q prefix command in SirPro), internal stamps are stripped from the working procedure and sequenced procedure. This prevents programmers from having to deal with these extra comment lines, and it prevents the stamps being generated into update procedures. Procedure stamps are also used as input data in some SirLib reports.
Administrators	Administrator IDs defined for the System profile (that is, 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 4) for the files they administer. For SirLib version 7.5 and higher, an unlimited number of Administrators may be specified for the system and for each file. For earlier SirLib versions, the limit of IDs is 12. If a site wants 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.
Procs exempt from stamping	If procedure stamping is "on," you might want to prevent SirLib comments from entering procedures that contain application help text, message text, or other literal information used by the application. You can do so by specifying a list of procedure prefixes for procedures in the system or for a file for which comments will not be inserted. The prefixes you specify for exempt procedures may be as many as 32 characters long. Wildcard characters such as * or ? are taken as literal values in these prefixes. For SirLib version 7.5 and higher, an unlimited number of prefixes may be specified for any file or the system as a whole. For earlier versions, the limit is four.

Note: Managed files are added to the SirLib system using the SIRLIB Administration screen. To remove a file from the SirLib system, press the F10 key, and SirLib removes 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

  As changes are applied, SirLib inserts 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 exempted from inserted commenting are not stamped):

  *** 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, as shown in the following representation.

If the FixFile field is left blank, the default FixFile from the File record is used.

SIRLIB 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 screen, PF12 initiates the cutover. If the cutover fails during any step, a failure message appears when the screen is refreshed, and you can 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 preceded by a backup of the managed file and its associated FixFile. It is also recommended that the Reconfiguration step not be bypassed unless you know 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 screen, where an error message is displayed.

After cutover completes, the date stamps for each activity are updated on the Cutover screen. 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 Checkout 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 Procedure 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 Procedure Locks screen, the procedure name is displayed to a maximum length of 33 characters. Following that, the screen shows the programmer owning the procedure, the source file for the checkout, the work file, 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.

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