SirLib programmer's reference
SirPro Procedure List screen
The SirPro screen shown above is the main working environment for the programmer in the SirLib-controlled environment. This screen, and others like it, provide access to all procedure activity in Model 204. Details on the use of SirPro, including managed update commands, are contained in the SirPro pages. Managed update prefix commands are the only part of SirPro discussed in this document.
The X, Q, N, K, and Z prefix commands are used to generate "working," Base, and Sequenced copies of procedures and to generate updates from those copies. The programmer types one of these managed update commands to the left of the selected procedure and presses Enter. SirPro then presents one of the managed update screens to get further details on the managed update. Those screens are shown in the following detailed sections.
Q (SEQUENCE) command
"Sequencing" is the managed update method by which programmers make copies of procedures to work on. In other systems, programmers make backup copies of procedures and then work on the original. In SirPro programmers never alter the original program code, but execute Q commands to get working and sequenced copies from which update procedures can be generated.
Updates must be done in a file other than the original, which is why procedure groups are recommended for development apsys.
SirPro screen for generating SEQ and working procedure copies
The Q command tells SirLib to generate both a copy of the selected procedure (the copy that the programmer will work on) and a "sequenced" copy of the procedure (a copy containing sequence or line numbers), which will later be used as comparison input for the Xcompare command. Building these copies is always the first programming step in generating a managed update. The Q prefix command presents a screen (Sequence Procedure) with the following input fields:
| Input procedure | The following two fields identify the source procedure, that is, the version of the procedure before it is changed. This information is copied from the entry on the SirPro procedure editor screen.
| ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Output procedures | SirLib is designed to work in a Model 204 subsystem (APSY) context using procedure groups.
The Q command creates two output procedures that must be in a different file from the source procedure. One of these procedures is used as a working copy, while the other procedure is used to determine any changes made to the working copy. Both of these procedures are formed by applying any staged updates to the indentified source procedure.
| ||||||||
| Location of control and update procedures |
SirLib uses a naming convention to identify any updates that should be applied to the source procedure before generating a working copy.
FixFile is searched for a "Control Procedure" whose name must be the name of the input procedure file prefixed with CONTROL.input-procedure-proc-file-name The Control Procedure identifies all projects with updates to procedures in the input procedure file. For each such project, FixFile is checked for Update Procedures that should be applied to the source procedure.
| ||||||||
| Replace existing procedures? | Overlaying a working copy or sequenced copy of a procedure can cause updates in progress to be lost.
The default for this field is Y. |
When the Q command is executed, SirLib looks in the
source file for a procedure named BASE.procname, where
procname is the name of the selected procedure.
If no such procedure is found, SirLib copies the procedure into the
target procedure in the Output file.
In addition, SirLib generates a sequenced copy of the procedure, named
whatever the programmer specified in the Sequenced Copy field on
this screen.
The sequenced copy of the procedure is identical to the unsequenced (or
working) copy, except that each line is prefixed with a sequence number.
If SirLib does find a BASE.procname procedure, it
looks for the CONTROL.filename procedure in the specified
FixFile.
A control procedure of the specified name must exist, or the Q command fails.
Noting the active projects in the control procedure, SirLib finds all
update procedure names that match the pattern:
file.project.procname
Where:
- file is the name of the input file for this operation.
- procname is the name of the selected input procedure.
- project is one of the identifiers in columns 1 to 8 of the control procedure.
All update procedure names that conform to this pattern are sorted by their
project and then by the sequence line numbers they affect.
This aggregate update is then applied to BASE.procname to
produce the sequenced and unsequenced output procedures.
In other words, the programmer doesn't just get a copy of the procedure
they request, they get a generated procedure composed of the Base procedure
with all updates applied to it.
If a project name is commented out in the control procedure, it is not included in the resulting sequenced and unsequenced output procedures. A Project name is commented out by placing an asterisk (*) in front of it in the control procedure. (This is how working versions of production procedures can be generated in development regions if the development region has active projects that do not exist yet in production).
The sequenced version of a procedure should never be changed, as it is the "before" image for the XCOMPARE that will eventually generate the update procedure. Sequence numbers should not concern programmers for the most part, though there are a few times when it is worth knowing something about how they work.
The Q command automatically begins sequencing at 10000 and
increments each line in the BASE.procname procedure by 10000.
As changes are generated, the XCOMPARE function generates new line numbers
for lines of code being inserted and replaced.
The XCOMPARE algorithm attempts to number the first new line of code
beginning with a sequence number 1 greater than its starting point in the
existing sequence (this applies to Inserts and Replaces: it is irrelevant
for Deletes).
Subsequent new lines which are part of the same update are incremented by a
power of 10 less than the last sequence of numbers for the section of code.
Later changes that apply to the same section again begin numbering at their
starting sequence number plus 1, and continue to increment at the next
lowest available power of 10.
Fortunately, the programmer doesn't have to understand any of this in order for it to work. The lower-order digit(s) of the sequence numbers in a SEQ procedure however will indicate the number of times a section of code has been changed. The sequence numbers themselves will indicate whether the XCOMPARE will be able to "fit" changes into the same section of code again. For example, a section of code with sequence numbers like the following indicates that changes will still "fit" in the hundreds and tens columns:
003451001 003452001 003453001
If an update procedure attempts to insert three lines of code after line 003452001, the resulting code is numbered like this:
003451001 003452001 003452102 003452202 003452302 003453001 003454001
Replace (./R) commands operate slightly differently than
Insert, but the outcome looks very similar.
When changes no longer "fit" within the sequence numbers XCOMPARE
will still generate an update procedure for this section of code, but the
update procedure will be unnecessarily long and SirLib might lose its
ability to detect update collisions.
In this case, a
Resequence is required, as described later in this page.
Once an initial update has been coded and the update procedure saved in the FixFile, all subsequent Q commands against the same procedure will generate copies containing the update, and sequence numbers in output sequenced versions of the procedure will reflect the insertion of the update code.
X (XCOMPARE) command
Prefixing a procedure by an X in SirPro tells the SirLib system to compare the specified procedure against a matching "sequenced" procedure, generating another procedure that containing the differences between the two. The X prefix command presents an XCOMPARE screen:
SirPro XCOMPARE screen
| Unsequenced input procedure | Identifies the procedure to be examined for changes, which was the object of an X command from a SirPro procedure list screen.
| ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Sequenced input procedure | Identifies the sequenced version of the input procedure, showing its contents prior to any changes.
| ||||||||
| Output update procedure | Identifies the location and name of an update procedure that will contain the changes that have been made to the sequenced version of the source procedure.
| ||||||||
| Replace existing update | Entering Y in this field allows the user to overwrite an existing version of the update procedure with the latest changes.
Programmers are always permitted to overwrite update procedures created under their userid when this switch is set to Y. The file administrator may have specified in the Administration options that programmers may not overwrite each other's update procedures either in this file or within the entire system. If this option is set, and an update procedure exists of the same name as the one being created in the target file, and the userid who created the update procedure (or last updated it) is not the same as the current user's ID, the generation of the update is not permitted. | ||||||||
| Enter Editor for update | Entering Y in this prompt places the generating user into an edit session on the new update procedure. The update procedure will have already been stored before the edit session is invoked, so PF3 or Quit may be used to exit the edit session without losing the update procedure. | ||||||||
| Synchronization count | This field allows programmers to set the number of lines that will be compared before the sequenced and unsequenced versions of the procedures are considered to be back in sync,
and further lines are no longer to be generated to the output update procedure (at least until the next mis-match). The default sync count value is 2, and this will work well for the vast majority of cases.
Increasing the sync count may reduce the number of difference lines found, resulting in smaller update procedures, or it may have no effect at all beyond a minor performance penalty in the XCOMPARE operation.
In a very few cases it may produce larger output procedures.
An entered value of | ||||||||
| Unlock this procedure? | Entering Y in this field makes the procedure available to other programmers in systems or files where procedures are locked to one updating user at a time.
Any value but Y allows the programmer to generate an update procedure but will retain the exclusive lock on the procedure (such as when a test integration is being run, and the programmer doesn't wish to relinquish control of the procedures being updated). If procedure locking is not turned on, the lock/unlock information is still maintained for historical reporting, but this switch has no actual effect in locking procedures. See Administration options for Procedure Locking options. |
N (NEW) command
Prefixing a procedure by an N in the SirPro edit screen tells the system to generate an update procedure, similar to that produced by X, but containing all lines of the specified procedure, because it is a new procedure to the system. The N prefix command presents a Create New Procedure screen:
Generating a New update procedure
| New procedure name | Identifies the new procedure, which was the object of an N command from a SirPro procedure list screen.
| ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Output update procedure | Identifies the location and name of an update procedure that will represent the creation of a new procedure.
| ||||||||
| Replace existing update | Entering Y in this field allows the user to overwrite an existing version of the update procedure with the latest changes.
Programmers are always permitted to overwrite update procedures created under their userid when this switch is set to Y. The file administrator may have specified in the Administration options that programmers may not overwrite each other's update procedures either in this file or within the entire system. If this option is set, and an update procedure exists of the same name as the one being created in the target file, and the userid who created the update procedure (or last updated it) is not the same as the current user's ID, the generation of the update is not permitted. | ||||||||
| Enter Editor for update | Entering Y in this prompt places the generating user into an edit session on the new update procedure. The update procedure will have already been stored before the edit session is invoked, so PF3 or Quit may be used to exit the edit session without losing the update procedure. |
K (KLOBBER) command
Prefixing a procedure with a K command in the SirPro edit screen directs SirLib to generate an update procedure that will cause the deletion of the indicated procedure. Managed update deletes are always logical deletes, allowing deleted procedures to be recovered at any time when the file is reconfigured. For this reason, an empty (zero-line) version of the deleted procedure is left in the file, and should not be physically deleted. The K prefix command presents a Klobber Procedure screen:
Generating a logical delete of a procedure in SirPro
| Procedure to erase | Identifies the procedure to be erased, which was the object of a K prefix command from a SirPro procedure list screen.
| ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Output update procedure | Identifies the location and name of an update procedure that will represent deletion of the procedure.
| ||||||||
| Replace existing update | Entering Y in this field allows the user to overwrite an existing version of the update procedure with the latest changes.
Programmers are always permitted to overwrite update procedures created under their userid when this switch is set to Y. The file administrator may have specified in the Administration options that programmers may not overwrite each other's update procedures either in this file or within the entire system. If this option is set, and an update procedure exists of the same name as the one being created in the target file, and the userid who created the update procedure (or last updated it) is not the same as the current user's ID, the generation of the update is not permitted. | ||||||||
| Enter Editor for update | Entering Y in this prompt places the generating user into an edit session on the new update procedure. The update procedure will have already been stored before the edit session is invoked, so PF3 or Quit may be used to exit the edit session without losing the update procedure. |
Z (RESEQUENCE) command
The sequence numbers generated by SirLib are for the most part of no concern to SOUL programmers. However, if a large number of update procedures are generated which effect the same areas of code in a procedure, further changes to the same areas may result in unnecessarily large update procedures. In addition, the process of untangling overlapping updates with SirLib will become more complex. This is should be a rare event, however if it does occur, a manager need only generate a resequence procedure by using the Z prefix command. The Z command presents a Resequence Procedure screen:
Resequencing a procedure in SirPro
| Resequence procedure | Identifies the procedure to be resequenced, which was the object of a Z prefix command from a SirPro procedure list screen.
| ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Output update procedure | Identifies the location and name of an update procedure that will cause resequencing of the procedure.
| ||||||||
| New starting number | The default is to begin renumbering with 10000. | ||||||||
| New increment | The default is to renumber in increments of 10000. | ||||||||
| Replace existing update | Entering Y in this field allows the user to overwrite an existing version of the update procedure with the latest changes.
Programmers are always permitted to overwrite update procedures created under their userid when this switch is set to Y. The file administrator may have specified in the Administration options that programmers may not overwrite each other's update procedures either in this file or within the entire system. If this option is set, and an update procedure exists of the same name as the one being created in the target file, and the userid who created the update procedure (or last updated it) is not the same as the current user's ID, the generation of the update is not permitted. | ||||||||
| Enter Editor for update | Entering Y in this prompt places the generating user into an edit session on the new update procedure. The update procedure will have already been stored before the edit session is invoked, so PF3 or Quit may be used to exit the edit session without losing the update procedure. |