SirLib change control: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
m (mention RKWeb equivalents)
 
(26 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<!--Page automatically generated by CMSTOWIK EXEC and will be
==SirLib main menu==
** automatically replaced ** -- any manual edits will be lost.
<var class="product">SirLib</var> functions are accessed through its main menu (the <b>Configuration and Change Control System</b> screen) in the SIRLIB subsystem. This screen is displayed by selecting item 2 from the [[RKTools#Integrating RKTools with other subsystems|RKTools System Main Menu screen]].  
You've been warned.  ..  (Page built by JAL at the SIRIUS VM; file: FUNPGNEW SYSUT2) -->
<!-- Page name: SirLib change control-->
<var class="product">SirLib</var> functions are accessed through a main menu in the <var class="product">SirLib</var> subsystem
(Selection 5 from the UL/SPF screen).
The main menu also allows specification of a <b>File</b> and <b>FixFile</b>.
The <b>File</b> field specifies the procedure file targeted for the requested activity.
The <b>FixFile</b> field specifies the <var class="product">Model 204</var> procedure file that contains the
<code>CONTROL.<i>filename</i></code> procedure and all update procedures for the
selected File.


<b>:SCREEN ID=LIBR08.SirLib Main Menu</b>
In [[RKWeb]], this screen is accessed by selecting <code>Build > Configure</code>, and [[Janus Web Legacy Support]] provides a facsimile of the TN3270 screen.
:SD L=01 C=01 BRIGHT. ----------- * * * Configuration and Change Control System * * * ------------


Options 1, 2 and 5 require a File to be input.
<p class="caption" style="width:450px">SirLib main menu</p>
If <b>FixFile</b> is <i>not</i> specified for Option 1, 2, or 5, the default
<p class="figure">[[File:SlibMainMenu.png|450px]]</p>
<b>FixFile</b> value as defined in the Administration option will be used.
 
If <b>FixFile</b> <i>is</i> specified for these options, the specified <b>FixFile</b> value
The <var class="product">SirLib</var> main menu also lets you specify a <b>Target file</b> and a <b>Fixes File</b>. The <b>Target file</b> field specifies the procedure file targeted for the requested activity. The <b>Fixes File</b> field specifies the <var class="product">Model&nbsp;204</var> procedure file that contains the
overrides the default.
<code>CONTROL.<i>filename</i></code> procedure and all update procedures for the selected file.
This allows, for instance, files to be reconfigured from different sets of
 
update procedures in different FixFiles.
Main menu options 1, 2, and 5 require a file specification: If <b>Fixes File</b> is <i>not</i> specified and you select option 1, 2, or 5, the default <b>Fix File</b> value defined in the <b>SIRLIB Administration</b> screen (main menu option 3) is used.
If <b>Fixes File</b> <i>is</i> specified for these options, the specified <b>Fixes File</b> value overrides the default.
This allows, for instance, files to be reconfigured from different sets of update procedures in different FixFiles.
<var class="product">SirLib</var>'s default FixFile is always <code>SIRLIBP</code>.
<var class="product">SirLib</var>'s default FixFile is always <code>SIRLIBP</code>.


Change Management functions are:
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 [[RKTools#Fast-pathing|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.


<table class="thJustBold">
<table class="thJustBold">
<tr><th>1. Project Definitions</th>
<caption>Main menu option descriptions</caption>
<td>Add, delete or change the Project identifiers in the FixFile assigned
<tr><th>1. Project Definition List</th>
to a managed file.  </td></tr>
<td>Add, delete, or change the project identifiers in the FixFile assigned to a managed file.  </td></tr>


<tr><th>2. Configure</th>
<tr><th nowrap>2. Apply changes (Reconfigure a file)</th>
<td>Apply and backout changes to files (that is; change the configuration
<td>Apply and backout changes to files (that is; change the configuration
of the file). </td></tr>
of the file). </td></tr>


<tr><th>3. Administration</th>
<tr><th>3. Administration</th>
<td>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 <var class="product">SirLib</var> system.</td></tr>
<td>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 <var class="product">SirLib</var> system.</td></tr>


<tr><th>4. Security</th>
<tr><th>4. Security</th>
<td>Defines access to <var class="product">SirLib</var> main menu options and to the Resequence command (<var>Z</var>) in <var class="product">SirPro</var>.
<td>Defines access to <var class="product">SirLib</var> main menu options and to the Resequence command (<var>Z</var>) in <var class="product">SirPro</var>.
Security settings only apply if <b>SECURE</b> is set to <code>Y</code> in the Administration function for the file (or for the system, if the file is not specifically set).</td></tr>
Security settings only apply if <b>Secure</b> is set to <code>Y</code> in the <b>SIRLIB Administration</b> screen for the file (or for the system, if the file is not specifically set).</td></tr>


<tr><th>5. Cutover</th>
<tr><th>5. Cutover</th>
<td>Does a large-scale clean-up of BASE. Procedures, update procedures,
<td>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.</td></tr>
project identifiers, and internal procedure stamps. This option is used infrequently; perhaps between major releases of an application.</td></tr>


<tr><th>6. Reports</th>
<tr><th>6. Reports</th>
Line 57: Line 49:
It is not specifically aware of the subsystem structure of a site's applications.
It is not specifically aware of the subsystem structure of a site's applications.
This allows <var class="product">SirLib</var> to manage applications that have a single procfile-to-subsystem
This allows <var class="product">SirLib</var> 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
relationship for all their subsystems, as well as those that run many subsystems from a single file or have multiple procedure files per subsystem.
single file or have multiple procedure files per subsystem.


<var class="product">SirLib</var> uses two pieces of information to track updates and
===Control and update procedures===
configuration status for a file.
<var class="product">SirLib</var> uses two pieces of information to track updates and configuration status for a file.
One way is via a single <code>FILE</code> record, kept in <code>SIRLIBD</code>, which holds security and
One is a single <code>FILE</code> record, kept in <code>SIRLIBD</code>, which holds security and administrative information for the file.
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.
The other is the file's Control procedure which is stored with the file's
<p>
update procedures in a FixFile.
[[SirLib implementation#Control procedures|Control procedures]] are named <var>CONTROL.<i>filename</i></var>, where
Control procedures are named <var>CONTROL.<i>filename></i></var>, where
<var class="term">filename</var> is the name of the managed file.
<i>filename</i> is the name of the managed file.
Control procedures contain a single line for each project name.
Control procedures contain a single line for each Project name.
A project is a logical change. </p>
A Project is a logical change.
<p>
Update procedures are linked to projects by naming convention.
[[SirLib implementation#Update procedures|Update procedures]] are linked to projects by naming convention. Update procedures are named: </p>
Update procedures are named:
<p class="syntax"><span class="term">filename</span>.<span class="term">project</span>.<span class="term">procname</span>
<p class="syntax"><span class="term">filename</span>.<span class="term">project</span>.<span class="term">procname</span>
</p>
</p>
Line 78: Line 68:
The third qualifier is the procedure to be changed.
The third qualifier is the procedure to be changed.


The project name qualifier provides a mechanism for grouping changes,
The project name qualifier provides a mechanism for grouping changes
and controlling and linking their application and backout.
and controlling and linking their application and backout.
When a project is added to a Control procedure, the whole set of changes
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.
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.
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 <var class="product">Model 204</var> editor by users
===Editing a control procedure===
Control procedures may be edited directly in the <var class="product">Model&nbsp;204</var> editor by users
who have been given access to the FixFile (FixFiles should be private files).
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.
However, the format of the lines of the procedure must be carefully maintained:
Each line of the <b>CONTROL</b> procedure must have a Project identifier in column 1-8
<ul>
(left-justified and blanks to the right if shorter than eight characters).
<li>Each line of the <var>CONTROL</var> procedure must have a project identifier in column 1-8 (left-justified and blanks to the right if shorter than eight characters). </li>
Column 9 must be blank and columns 10 through 72 may contain a comment.
 
The Project Identifier must be in uppercase.
<li>Column 9 must be blank, and columns 10 through 72 may contain a comment. </li>
The optional comment may be in mixed case.
 
If a Project name begins with an asterisk (<tt>*</tt>), <var class="product">SirLib</var> considers
<li>The project identifier must be in uppercase. The optional comment may be in mixed case. </li>
the entire line a comment.
 
<li>If a project name begins with an asterisk (<tt>*</tt>), <var class="product">SirLib</var> considers the entire line a comment.
Updates are backed out by commenting-out project names in this way, and
Updates are backed out by commenting-out project names in this way, and
reconfiguring a file.
reconfiguring a file. <var class="product">SirLib</var> skips the commented line, applying all previous and subsequent updates. </li>
<var class="product">SirLib</var> skips the commented line, applying all previous and subsequent updates.
</ul>


The proper way to maintain Projects is via Option 1 in <var class="product">SirLib</var>.
The proper way to maintain projects is through Option 1 in the <var class="product">SirLib</var> main menu.
This screen allows users to add, change and delete Project identifiers.
The resulting screen lets you add, change, and delete project identifiers.
It verifies the format of the Project identifier, automatically converting
It verifies the format of the project identifier, automatically converting it to uppercase.
it to upper case.
To access this screen, a file must be specified on the main menu: project
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.
identifiers are always file-specific, as are the Control procedures in which
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.
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
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 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.
Simple actions taken on these nodes can have major consequences.
Of particular importance are the following issues:
Of particular importance are the following issues:
Line 118: Line 102:
<ul>
<ul>
<li>Order
<li>Order
<p>Updates are applied in the order shown in the Control procedure.
<p>
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
A project, being the name of a logical change, may point to many update
procedures (physical changes).</p>
procedures (physical changes).</p>
<p>
<p>
If the order of project names is altered in the control procedure, and update
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.
procedures across projects affect the same section of the same procedure, the
In this case, the <b>Apply changes (ReConfigure a file)</b> option in <var class="product">SirLib</var> tells you the update
sequence numbers in later updates may not match those in the existing procedure,
procedure that failed to apply and the sequence number where the error occurred.  </p></li>
and the attempt to reconfigure the file will fail.
In this case the ReConfigure option in <var class="product">SirLib</var> will tell the user the update
procedure that failed to apply and the sequence number where the error occurred.  </p>


<li>Logical Dependency
<li>Logical dependency
<p>There is no way <var class="product">SirLib</var> or any other change management system can know about
<p>
There is no way <var class="product">SirLib</var> or any other change management system can know about
logical dependencies between source code changes in different update procedures.
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
A %variable declared in one update may be used by code built by another update procedure.
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
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.</p>
the %variable is missing from the resulting procedure.</p>
<p>
<p>
It is important that physical changes which are logically dependent upon on another
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.</p></li>
be applied and backed out together, and this is done by linking them to the same project.</p>
</ul>
</ul>


From the Project Definition screen, PF2 gives access to an edit session
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.
in which you 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
You edit in mixed-case mode. When you exit the edit session, the lines of the edit procedure are converted to TEXT fields in <code>SIRLIBD</code>, and they are linked to the appropriate project identifier.
exited, the lines of the procedure are converted to TEXT fields in <code>SIRLIBD</code>, and
linked to the appropriate Project Identifier.


==Configuring files (applying updates)==
==Configuring files (applying updates)==
Applying updates is always done one <i>file</i> at a time.
Applying updates is always done one <i>file</i> at a time.
The process is called <b>ReConfiguring</b> a file.
The process is called <var class="term">ReConfiguring</var> a file.
The file and FixFile are selected on the main menu at the time Option 2 is selected.
 
The <b>SirLib File Reconfiguration</b> screen is then displayed:
You invoke a reconfiguration by specifying the target file and the fix file on the SirLib main menu, then selecting Option 2, <b>Apply changes (Reconfigure a file)</b>.
This produces a screen like the following (which results from target file M204PROC and fix file M204FIX):


<b>:SCREEN ID=LIBR07.Applying Fixes/Changes</b>
<p class="caption" style="width:450px">SirLib file reconfiguration</p>
:SD L=01 C=02 BRIGHT. ------------------- * * * SIRLIB File ReConfiguration * * * ----------------
<p class="figure">[[File:SlibReconfigure.png|450px]]</p>


The above screen shows how the programmer applies changes to a file.
===Applying Fixes/Changes===
Pressing Enter while on this screen applies all active updates in the
You use the <b>SirLib File ReConfiguration</b> 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.
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 <var class="product">SirLib</var> attempts to apply changes to it,
If a procedure is locked when <var class="product">SirLib</var> attempts to apply changes to it, the reconfiguration fails, and a message is displayed identifying the procedure that could not be updated by <var class="product">SirLib</var>. 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.
the ReConfiguration fails and a message is displayed identifying the
Reconfiguration may be run as many times as needed, until all changes
procedure that could not be updated by <var class="product">SirLib</var>.
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.
are properly applied.
When a ReConfiguration fails in this manner the file may be left in a state
<p>
where some procedures are deleted.
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. </p>
The faulty update should be fixed or commented out and reconfiguration run again.


===Backing out changes===
===Backing out changes===
ReConfiguration ignores all projects that are prefixed by an asterisk (<tt>*</tt>).
Reconfiguration ignores all projects that are prefixed by an asterisk (<tt>*</tt>). 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 <var>DUMP/RESTORE</var> or other external backups of the file.
The manager who wishes to backout all updates linked to a project, can
<p>
do so by commenting out the project name in the Project screen, and
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 <var class="product">SirLib</var> checks for updates linked to projects.
reconfiguring the file using option 2.
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. </p>
This takes only a few minutes of work and is independent of <var>DUMP/RESTORE</var> or other
<p>
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 <var class="product">SirLib</var> 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
Each active Project in the Control procedure must be linked to at least
one update, or the ReConfiguration will fail.
one update, or the reconfiguration fails. </p>
If updates are deleted or renamed such that none link to a particular project,
<p>
the project name should also be commented out or deleted.
If updates are deleted or renamed such that none link to a particular project, the project name should also be commented out or deleted. </p>


===Applying updates in batch mode===
===Applying updates in batch mode===
Line 207: Line 168:
<li><var class="term">fixfile-name</var> is the file that contains the update procedures.</li>
<li><var class="term">fixfile-name</var> is the file that contains the update procedures.</li>


<li><var class="term">source-filename</var> is optional and allows fixes originally written
<li><var class="term">source-filename</var> is optional and allows fixes originally written against one procedure file to be applied to a different file.
against one procedure file to be applied to a different file.
<p>
<p>
This is useful if the source procedure file in the development environment
This is useful if the source procedure file in the development environment
has a different name than the procedure file in production.
has a different name than the procedure file in production.
In the standard case, where the target and source procedure files are the same
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
or have the same name, this parameter can either be left blank or can
be the same as the target file. </p></li>
be the same as the target file. </p></li>
</ul>
</ul>


The following command:
The following command:
<p class="code"><nowiki>SIRLIB BATCH SIRMON SIRFIXES SIRMON
<p class="code">SIRLIB BATCH SIRMON SIRFIXES SIRMON
</nowiki></p>
</p>
results in the same changes being applied to subsystem SIRMON as:
results in the same changes being applied to subsystem SIRMON as:


<p class="code"><nowiki>SIRLIB BATCH SIRMON SIRFIXES
<p class="code">SIRLIB BATCH SIRMON SIRFIXES
</nowiki></p>
</p>


The following example shows changes, originally written against <code>DEVPPROC</code>
The following example shows changes, originally written against <code>DEVPPROC</code>, being applied to <code>PRODPROC</code> (with the change decks coming from <code>SIRLIBD</code>):
being applied to <code>PRODPROC</code> (with the change decks coming from <code>SIRLIBD</code>):
<p class="code">SIRLIB BATCH PRODPROC SIRLIBD DEVPROC
<p class="code"><nowiki>SIRLIB BATCH PRODPROC SIRLIBD DEVPROC
</p>
</nowiki></p>
This command does not have to be placed in a batch job: it can be
This command does not have to be placed in a batch job: it can be
typed directly in at <var class="product">Model 204</var> command level, or it can be inserted in the
typed directly in at <var class="product">Model&nbsp;204</var> command level, or it can be inserted in the User 0 stream, or invoked in an IODEV3 thread.
User 0 stream, or invoked in an IODEV3 thread.


One use of the batch <var class="product">SirLib</var> command is to place the command for each
One use of the batch <var class="product">SirLib</var> 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.
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
To aid in batch debugging and job control, SIRLIB also sets a global
<var>SIRLIBFAILURE</var> to 0 if the configuration command worked correctly, and
<var>SIRLIBFAILURE</var> to 0 if the configuration command worked correctly, and to 1 if the command failed.
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.
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==
==Administering system and file profiles==
<b>:SCREEN ID=LIBR30.SirLib Administration screen</b>
:SD L=01 C=01 BRIGHT. ------------------- * * * SIRLIB Administration * * * --------------------


The <var class="product">SirLib</var> Administration Option allows users to define a custom <var class="product">SirLib</var>
<p class="caption" style="width:450px">SIRLIB Administration</p>
profile for each file.
<p class="figure">[[File:SlibAdministration.png|450px]]</p>
If the Administration option is selected with no file specified on the
 
main menu, then the System Profile is being defined or changed.
The <var class="product">SirLib</var> <b>Administration</b> option lets you define a custom <var class="product">SirLib</var> profile for each file. If you select the SirLib main menu <b>Administration</b> option with no target file specified, then the system profile is being defined or changed. If a <b>Target file</b> value <i>is</i> specified on the main menu, then a file-specific profile is being defined or changed.
If a <b>File</b> value <i>is</i> specified on the main menu, then a file-specific
profile is being defined or changed.


Only users defined to the <var>ADMIN SCLASS</var> in the <var class="product">SirLib</var> subsystem definition
Only users defined to the <var>ADMIN SCLASS</var> in the <var class="product">SirLib</var> subsystem definition
are allowed access to the Administration option without specifying a file.
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.
Only users defined as Administrators in the System profile are
allowed access to File profiles.


The settings on the <b>SirLib Administration</b> screen are described below.
The settings on the <b>SIRLIB Administration</b> screen are described below. If any of these settings is left blank on a File profile, <var class="product">SirLib</var> 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.
If any of these settings is left blank on a <b>File</b> profile, <var class="product">SirLib</var>
takes its behavior from the <b>System</b> profile setting.
If the option is left blank on the System profile, default action varies, but
is noted in the descriptions below.


<table class="thJustBold">
<table class="thJustBold">
<tr><th>File</th>
<tr><th>File</th>
<td>A file name is displayed only if one was specified on the main menu. The file name cannot be modified on the <b>SIRLIB Administration</b> screen. If no file was specified on the main menu, then this field will read <b>Defaults</b>.</td></tr>


<td>A file name is displayed only if one was specified on the main menu. The file name cannot be modified on the Administration screen.
<tr><th>Fix File</th>
If no file was specified on the main menu, then this field will read <b>System Defaults</b>.</td></tr>
<td>A FixFile is a <var class="product">Model 204</var> procedure file that contains update procedures and a <var>CONTROL.<i>filename</i></var> procedure for a file or set of files. Any number of files may share the same FixFile.  
 
<tr><th>Changes File</th>
<td>A Changes File (FixFile) is a <var class="product">Model 204</var> procedure file that contains update procedures and a <var>CONTROL.<i>filename</i></var> procedure for a file or set of files. Any number of files may share the same FixFile.  
<p>
<p>
The default FixFile for all of <var class="product">SirLib</var> is <b>SIRLIBP</b>, a <var class="product">Model&nbsp;204</var> procedure file that was created as part of the <var class="product">SirLib</var> installation process. If a different FixFile is specified as the default for a managed file, <var class="product">SirLib</var> options 1, 2, 5, and all <var class="product">SirLib</var> reports will look in the new FixFile for update procedures and the control procedure.</p></td></tr>
The default FixFile for all of <var class="product">SirLib</var> is <b>SIRLIBP</b>, a <var class="product">Model&nbsp;204</var> procedure file that was created as part of the <var class="product">SirLib</var> installation process. If a different FixFile is specified as the default for a managed file, <var class="product">SirLib</var> options 1, 2, 5, and all <var class="product">SirLib</var> reports look in the new FixFile for update procedures and the control procedure.</p></td></tr>


<tr><th>Single Checkout</th>
<tr><th>Single Checkout</th>
<td>This switch affects the behavior of the <var>Q</var> command in <var class="product">SirPro</var>.
<td>This switch affects the behavior of the <var>Q</var> command in <var class="product">SirPro</var>.
The default, <code>N</code>, allows multiple programmers to update the same procedure at the same time, and leaves it up to <var class="product">SirLib</var> to handle possible collisions when the update procedures are applied.
The default, <code>N</code>, allows multiple programmers to update the same procedure at the same time, and leaves it up to <var class="product">SirLib</var> to handle possible collisions when the update procedures are applied. The administrator may switch this option to <code>Y</code> to force a "checkout" to occur when the <var>Q</var> command is executed against a procedure.
The administrator may switch this option to <code>Y</code> to force a "checkout" to occur when the <var>Q</var> command is executed against a procedure.
<p>
<p>
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.
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 <var>Q</var> command is executed. The checkin is optional on the <var>X</var> screen, when the final update procedure is being generated.
The checkout occurs automatically when a <var>Q</var> command is executed. The check-in is optional on the <var>X</var> screen, when the final update procedure is being generated.
The programmer simply checks <var>Y</var> at the bottom of the Xcompare screen to unlock the procedure.
The programmer simply checks <var>Y</var> at the bottom of the Xcompare screen to unlock the procedure. </p>
Users in the <var class="product">SirLib</var> ADMIN sclass can view and remove procedure locks by Option 7 from the <var class="product">SirLib</var> main menu.</p>
<p>
Users in the <var class="product">SirLib</var> <var>ADMIN</var> subsystem user class (<var>SCLASS</var>) can view and remove procedure locks by Option 7 from the <var class="product">SirLib</var> main menu.</p>
<p>
<p>
Regardless of the setting of this switch, <var class="product">SirLib</var> stores a <i>lock</i> record for each procedure that is the subject of a <var>Q</var> (Sequence) command.
Regardless of the setting of this switch, <var class="product">SirLib</var> stores a <b>lock</b> record for each procedure that is the subject of a <var>Q</var> (Sequence) command.
This allows managers to view a list of procedures being updated even when the procedure is not actually locked.</p></td></tr>
This allows managers to view a list of procedures being updated even when the procedure is not actually locked.</p></td></tr>


<tr><th>Overwrite protection</th>
<tr><th>Overwrite protection</th>
<td>This switch affects the behavior of the <var class="product">SirPro</var> <var>X</var> prefix command.
<td>This switch affects the behavior of the <var class="product">SirPro</var> <var>X</var> prefix command.
By default <var class="product">SirPro</var> allows users to overwrite each others' update procedures, provided a switch is checked on the Xcompare panel when generating the second update procedure.
By default <var class="product">SirPro</var> 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.
<p>
However if Overwrite is set to <code>N</code> on this panel, <var class="product">SirLib</var> will not allow a programmer to replace an update procedure generated by another user.</td></tr>
The <b>Overwrite</b> switch on the <b>Administration</b> screen never stops programmers from overwriting their own changes.
However if <b>Overwrite</b> is set to <code>N</code> on this screen, <var class="product">SirLib</var> does not allow a programmer to replace an update procedure generated by another user.</p></td></tr>


<tr><th nowrap>Require Project Identifiers</th>
<tr><th nowrap>Require Change Identifiers</th>
<td>The system default is to allow programmers to generate update procedures for any project, whether or not the project name is listed in the <code>CONTROL.<i>filename</i></code> procedure for the file.
<td>The system default is to allow programmers to generate update procedures for any project, whether or not the project name is listed in the <code>CONTROL.<i>filename</i></code> procedure for the file.
If this toggle is set to <code>Y</code>, programmers may only name their update procedures using project names that exist in the control procedure. Note the format of update procedure names is:
If this toggle is set to <code>Y</code>, programmers may only name their update procedures using project names that exist in the control procedure.  
<p class="syntax"><span class="term">filename</span>.<span class="term">project</span>.<span class="term">proc-name</span>
<blockquote class="note"><p><b>Note:</b> The format of update procedure names is: </p>
</p>
<p class="syntax"><span class="term">filename</span>.<span class="term">project</span>.<span class="term">procname</span> </p>
The <var class="term">project</var> qualifier in the above naming convention is the value that is checked when this option is set to <code>Y</code>.
<p>
The <var class="term">project</var> qualifier in the above naming convention is the value that is checked when this option is set to <code>Y</code>. </p>
</blockquote>
<p>
<p>
Requiring project names to exist before updates are linked to them allows the manager to specify destinations for update procedures,
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. </p>
and it may prevent changes from being left out of a release by inadvertent misspellings of project names by programmers. </p>
<p>
<p>
The advantage of <i>not</i> 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.
The advantage of <i>not</i> 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.
Line 312: Line 253:


<tr><th>Keep History</th>
<tr><th>Keep History</th>
<td>Setting this switch to <code>N</code> reduces the amount of historical information kept by <var class="product">SirLib</var>. Certain history records are maintained regardless of this setting, such as ReConfigurations and Cutovers.</td></tr>
<td>Setting this switch to <code>N</code> reduces the amount of historical information kept by <var class="product">SirLib</var>. Certain history records are maintained regardless of this setting, such as Reconfigurations and Cutovers.</td></tr>


<tr><th>Secure</th>
<tr><th>Secure</th>
Line 323: Line 264:
<p>
<p>
If on the default System profile, <b>Secure</b> is <code>N</code>, specific files that require security can override this setting by specifying <code>Y</code> for <b>Secure</b> on their administration screen.
If on the default System profile, <b>Secure</b> is <code>N</code>, specific files that require security can override this setting by specifying <code>Y</code> for <b>Secure</b> 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.
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. </p>
<p>
A blank setting for <b>Secure</b> on a file record tells <var class="product">SirLib</var> to use the System Defaults for that file.
A blank setting for <b>Secure</b> on a file record tells <var class="product">SirLib</var> to use the System Defaults for that file.
If <b>Secure</b> is left blank in the system profile, <var
If <b>Secure</b> is left blank in the system profile, <var
class="product">SirLib</var> assumes it should be <code>N</code>.</p></td></tr>
class="product">SirLib</var> assumes it should be <code>N</code>.</p></td></tr>
<tr><th>Administrator IDs</th>
<td>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 <var class="product">SirLib</var> and <var class="product">SirPro</var> on an honor system basis, one of the simplest ways to do it
is to define all users to the ADMIN SCLASS of <var class="product">SirLib</var>, and either turn security off, or let each user build whatever permissions they require for themselves or their development group.</td></tr>


<tr><th>Procedure Stamping</th>
<tr><th>Procedure Stamping</th>
<td>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.
<td>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 (<i>Y</i> to turn stamping on, <i>N</i> to turn it off) on the Administrator setup screen.
Procedure stamping may be set on or off globally (<code>Y</code> to turn stamping on, <code>N</code> to turn it off) on the Administrator setup screen.
<p>
<p>
Internal procedure stamps can be deleted by <var class="product">SirLib</var> when the file is "Cutover" (refer to [[#cutover|Release cutover]]).
Internal procedure stamps can be deleted by <var class="product">SirLib</var> when the file is "Cutover" (refer to [[#cutover|Release cutover]]).
Line 350: Line 285:
</blockquote></td></tr>
</blockquote></td></tr>


<tr><th>Exempt Prefixes</th>
<tr><th>Administrators</th>
<td>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.
<td>Administrator IDs defined for the System profile (that is, when no file is specified on entering the <b>Administration</b> option) are given access to Administration functions for all files.
This prevents <var class="product">SirLib</var> comments from entering procedures that contain application help text, message text or other literal information used by the application.
These System Administrators may then access Administration options to set File profiles. Users defined as Administrators for a File have access to <b>Security</b> (Option 4) for the files they administer.
Prefixes for exempt procedures may be up to 32 characters long. Wild card characters such as <code>*</code> or <code>?</code> are taken as literal values in these prefixes.
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.
As many as four prefixes may be specified for any file or the system as a whole. There are no default exempt prefixes.</td></tr>
<p>
If a site wants to use <var class="product">SirLib</var> and <var class="product">SirPro</var> on an honor system basis, one of the simplest ways to do it
is to define all users to the ADMIN SCLASS of <var class="product">SirLib</var>, and either turn security off, or let each user build whatever permissions they require for themselves or their development group.</p></td></tr>
 
<tr><th nowrap id="procexempt">Procs exempt from stamping</th>
<td>If procedure stamping is "on," you might want to prevent <var class="product">SirLib</var> 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 <b>not</b> be inserted.
<p>
The prefixes you specify for exempt procedures may be as many as 32 characters long. Wildcard characters such as <code>*</code> or <code>?</code> 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. </p></td></tr>
</table>
</table>


Files are added to the <var class="product">SirLib</var> system via the <b>Administration</b> screen.
<p class="note"><b>Note:</b> Managed files are added to the <var class="product">SirLib</var> system using the <b>SIRLIB Administration</b> screen. To remove a file from the <var class="product">SirLib</var> system, press the F10 key, and <var class="product">SirLib</var> removes all security, history, procedure locks, administration, and user privileges for the file. If the file has already been added to the <code>SIRLIB</code> subsystem, use [[System requirements for Application Subsystems#Overview of the SUBSYSMGMT interface|SUBSYSMGMT]] to remove it. </p>
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 <b>??</b>.
 
To remove a file from the <var class="product">SirLib</var> system, press PF10,
and <var class="product">SirLib</var> will remove all security, history, procedure locks,
administration, and user privileges for the file.
If the file has already
been added to the <var class="product">SirLib</var> subsystem, use SUBSYSMGMT to remove it.
 
<div id="cutover"></div>
==Release cutover==
<!--Caution: <div> above-->


==<b id="cutover"></b>Release cutover==
One way to use <var class="product">SirLib</var> is to keep update procedures forever, allowing
One way to use <var class="product">SirLib</var> is to keep update procedures forever, allowing
unlimited flexibility to reconfigure a system to a previous state.
unlimited flexibility to reconfigure a system to a previous state.
Line 382: Line 312:
Performing a cutover causes the following <var class="product">SirLib</var> processing:
Performing a cutover causes the following <var class="product">SirLib</var> processing:
<ul>
<ul>
<li>ReConfiguration
<li>Reconfiguration
<p>Cutover invokes a full file ReConfiguration to ensure that all
<p>
Cutover invokes a full file Reconfiguration to ensure that all
updates are applied.
updates are applied.
This step can be bypassed with a switch on the Cutover screen.</p></li>
This step can be bypassed with a switch on the Cutover screen.</p></li>


<li>Delete Update procedures
<li>Delete update procedures
<p>All update procedures in the FixFile that have the cutover file as a
<p>
first qualifier are deleted whether or not they are linked to an active project.</p></li>
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.</p></li>


<li>Delete Project Identifiers
<li>Delete project identifiers
<p>All lines in the control procedure for the file
<p>
(CONTROL.<i><cutover-file></i>) are deleted.</p></li>
All lines in the control procedure for the file
(<var>CONTROL.<i><cutover-file></i></var>) are deleted.</p></li>


<li>Delete Base Procedures
<li>Delete Base procedures
<p>All procedures beginning with <code>BASE.</code> are deleted from the target cutover file.</p></li>
<p>
All procedures beginning with <code>BASE.</code> are deleted from the target cutover file.</p></li>


<li>Delete Comments
<li>Delete comments
<p>When changes have been applied, <var class="product">SirLib</var> will have inserted a comment
<p>
like the following at the beginning of each changed procedure:  </p>
As changes are applied, <var class="product">SirLib</var> inserts a comment like the following at the beginning of each changed procedure:  </p>
<p class="code"><nowiki>*** F2BALES Applied by ... ***
<p class="code"><nowiki>*** F2BALES Applied by ... ***
</nowiki></p>
</nowiki></p>
<p>
<p>
These comments are deleted at cutover, and a single new comment reading as follows
These comments are deleted at cutover, and a single new comment reading as follows is inserted (procedures [[#procexempt|exempted]] from inserted commenting are not stamped): </p>
is inserted (procedures excluded from inserted commenting are not stamped;
see System Setup): </p>
<p class="code"><nowiki>*** Cutover on DD/MM/YY
<p class="code"><nowiki>*** Cutover on DD/MM/YY
</nowiki></p>
</nowiki></p>
Line 414: Line 346:
</ul>
</ul>


Cutover is initiated from the <var class="product">SirLib</var> main menu using option 4.
Cutover is initiated from the <var class="product">SirLib</var> 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.  
The file to be cutover is specified on the main menu along with the
<p>If the <b>FixFile</b> field is left blank, the default FixFile from the File record is used.</p>
FixFile from which the changes are to be applied and deleted.
If the <b>FixFile</b> field is left blank, the default FixFile from the File
record is used.


<b>:SCREEN ID=LIBR15.Cutover Information Display</b>
<p class="caption" style="width:450px">SIRLIB Cutover</p>
:SD L=01 C=01 BRIGHT. ---------------------- * * * SIRLIB File Cutover * * * ----------------------
<p class="figure">[[File:SlibCutover.png|450px]]</p>


A scrollable panel at the bottom of Cutover screen lets you
A scrollable panel at the bottom of the Cutover screen lets you
view the changes that are to be applied.
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.
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 remaining fields on the Cutover screen display information to help
the file manager determine the state of the file and changes associated
the file manager determine the state of the file and changes associated
with the file.
with the file. Existing projects are displayed in a block at the bottom of the screen. Dates and times are displayed for the first <var class="product">SirLib</var> transaction for this file, the first and last reconfiguration, and the most recent cutover.
Existing projects are displayed in a block at the bottom of the screen.
Dates and times are displayed for the first <var class="product">SirLib</var> transaction for this
file, the first and last reconfiguration, and the most recent cutover.
All of this information is refreshed after a successful cutover.
All of this information is refreshed after a successful cutover.


From the Cutover panel, PF12 initiates the cutover.
From the Cutover screen, PF12 initiates the cutover.
If the cutover fails during any step a failure message appears when the
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
screen is refreshed, and you can check the date and time stamps
for each activity to see which step failed.
for each activity to see which step failed.
Refer to [[SirLib problem resolution]] for advice on error recovery.
Refer to [[SirLib problem resolution]] for advice on error recovery.


Because the results of a cutover are irreversible it is recommended
Because the results of a cutover are irreversible, it is recommended
that cutovers always be prefaced by a backup of the managed file and
that cutovers always be preceded by a backup of the managed file and
its associated FixFile.
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.
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
Care should be taken to verify that changes are not incorrectly
"commented out" in the Control procedure.
"commented out" in the Control procedure.
<p>
If any step fails to execute properly, processing stops at that step and
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
control is returned to the Cutover screen, where an error message is
displayed.
displayed. </p>
After cutover compleyes, the date stamps for each activity will be
<p>
updated on the Cutover panel.
After cutover completes, the date stamps for each activity are updated on the Cutover screen. Verify these dates and times before exiting. </p>
The user should verify these dates and times before exiting.


==View/Clear procedure locks==
==View/Clear procedure locks==
Procedures always have a record posted whenever a programmer takes a
Procedures have a record posted whenever a programmer takes a
managed update copy of the procedure using the <var>Q</var> command.
managed update copy of the procedure using the <var>Q</var> command.
This record becomes a lock when the manager has set <b>Single User Update</b> to
This record becomes a lock when the manager has set <b>Single Checkout</b> to <code>Y</code> in the <b>Administration</b> screen.
<code>Y</code> in the Administration screen.
Programmers unlock procedures by executing an <var>X</var> (Xcompare) against the locked procedure, specifying <code>Y</code> in the field on the Xcompare screen that asks whether the procedure should be unlocked.
Programmers unlock procedures by executing an <var>X</var> (Xcompare) against
 
the locked procedure, specifying <code>Y</code> in the field on the Xcompare
The <b>View/Clear Procedure Locks</b> option in <var class="product">SirLib</var> is a way for managers to track and
screen that asks whether the procedure should be unlocked.
The <b>View/Clear locks</b> option in <var class="product">SirLib</var> is a way for managers to track and
modify procedure locking.
modify procedure locking.


<b>:SCREEN ID=LIBR31.View/Clear Procedure Locks</b>
<p class="caption" style="width:450px">View/Clear Procedure Locks</p>
:SD L=01 C=01 BRIGHT. ---------------------- * * * View/Clear Procedure Locks * * * ----------------
<p class="figure">[[File:SlibProcLocks.png|450px]]</p>


Access to this option is determined by ADMIN SCLASS membership.
Access to this option is determined by <var>ADMIN SCLASS</var> membership.


If the manager wishes to clear a lock, an "S" is placed to the
To clear a lock, place an <code>S</code> 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 <b>View/Clear Procedure Locks</b> function, only those procedures locked from the specified file are displayed.
left of the procedure name.
The list may be scrolled and sorted with the displayed PF keys.
Locks are cleared when ENTER is pressed.
If the View/Clear Locks function is entered with a filename specified on
the main menu, only those procedures locked from the specified file are
displayed.
The list may be scrolled and sorted via the displayed PF keys.


In the View/Clear locks option, the procedure name is displayed out to
In the <b>View/Clear Procedure Locks</b> screen, the procedure name is displayed to a maximum length of 33 characters.
33 characters.
Following that, the screen shows the programmer owning the procedure,
Following that, the display 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.
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.


==See also==
==See also==

Latest revision as of 23:26, 21 June 2017

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