Programmer's ROM - The Computer Language Library

home *** CD-ROM | disk | FTP | other *** search

/ Programmer's ROM - The Computer Language Library / programmersrom.iso / ada / pdl / docmgr.doc < prev next >

Wrap

Text File | 1988-05-03 | 208.1 KB | 5,161 lines

:::::::::::::: catmgr.rno :::::::::::::: .PG .HL ^&CATALOG MANAGER\& .SK .HL +1 ^&Description\& .SK .P A catalog is a database of configuration items (CI), and the catalog manager encompasses the procedures that allow users to manage catalogs, access CIs and add new CIs. A catalog contains CIs, a keyword list and a property index. CIs will have properties to describe them, and when a CI is added to the catalog its properties are stored in the index so it can be referenced by property. A property is a keyword, value pair, and all the allowable keywords for the catalog are stored in its keyword list. There are three states that a keyword can have: optional, required and invalid. Invalid keywords are ones that once were valid. .P Libraries can only be STORED into the catalog as a CI version if all the properties are valid. In this way a user can use an invalid keyword when selecting CIVs from the index since there may be versions that were added to the catalog before the keyword was invalid. Although it is possible to define a keyword as invalid from the start it serves no useful purpose. .P There are four procedures that act on catalogs. CREATE_CATALOG creates new catalogs, and any number of catalogs can be created as long as they have unique names. A catalog name must be an Ada identifier. LIST_CATALOGS will list all the catalogs in the system. It can be given a pattern in which case it will only print out those catalogs whose name matches the pattern. OPEN_CATALOG will open a specific catalog and put the user in an interactive tool where he can select CIVs, fetch and store them. In the interactive tool the user can also print out various information stored in the catalog about the CIVs. CHECK_CONSISTENCY will read the structure of a catalog and the information in it and check that it is not corrupt. It will report any inconsistencies it finds. It does not do any actual fixing, but there are ways for privileged users to fix the inconsistencies. .HL ^&Configuration Item Versions\& .SK .P A CI version will have file components and properties. The file components are the source files that go into making up the version. A file component can be any type of text; code or documentation. Properties are keyword, value pairs associated with a version that describe it in some way. For example, a keyword might be subject, and a value for that keyword might be ADA_pdl. Both keywords and values must be ada identifiers. When an item library is added to a catalog to become a CIV its properties must have keywords that are valid for that catalog, and they must include all required keywords. If there are any errors when a library is being added to the catalog, the error is reported and the library is left where it is. Item libraries are managed by the Item Library Manager procedures. .HL ^&Configuration Identification\& .SK .P A CI id consists of two parts, a name which is an ada identifier and the version which is assigned by the catalog manager. The version is a number beginning at 1 with the version being assigned sequentially. If a CIV is only fetched for update then its versions will be a single number. The updates of a CI are called trunk versions. When a CIV is fetched as a branch the version gets two more numbers when it is stored. The first number indicates what branch this is and then the second indicates that this CIV is the first version along the branch. For example, a branch from the CIV 'example 2' would be given the CI id 'example 2.1.1' when it was stored. This new CIV can also be checked out for updating, and when the store is done the CI id would be 'example 2.1.2'. These CIVs begin a trunk along the branch. It is also possible to have branches from branches. For example, the STORE of a branch from 'example 2.1.2' would be given a CI id of 'example 2.1.2.1.1'. It should be noted that in addition to making the version numbers longer, branches add some computational overhead, so operations with branches will take a little longer depending on how many levels of branching there is. .HL ^&Using the Catalog Manager\& .SK .P A project should set up a catalog in which to put its CIs. When CREATE_CATALOG is invoked the user must supply a directory where the catalog will keep its data files. The catalog directory is like an Ada program library: you may go into it and list the files, but if you change anything you may corrupt the catalog beyond repair. .P It is suggested that the project create one directory for catalog related file and create the catalog as a subdirectory of the designated directory. The user directories and item libraries can also be subdirectories of this directory enabling a backup of all documentation system data to be collected easily. .P When the catalog is created a password is prompted for. This password should then only be given out to those that NEED to know like a CM coordinator. The only command that changes the catalog which is not privileged is MODIFY_PROPERTY, but it only affects the index. Once the catalog is created the creator should lose no time in opening it and defining the keywords allowed and add any item libraries pending. .HL ^&Example Session\& .SK .P A user beginning to use the system for the first time would probably execute a sequence of commands like the following: .LT LIST_CATALOGS; -- to find out what catalogs are available. -- Suppose there was a catalog called "PROJECT" that is the user's -- project catalog. OPEN_CATALOG ("PROJECT"); -- opens the catalog. -- Note that the names are Ada identifiers so case is unimportant. LIST_KEYWORDS; -- lists the possible keywords to select by. -- Suppose that there are keywords language, type, subject, -- implementor, group, and that the user is interested in finding -- the list package mentioned earlier with the requirement that -- it be written in Ada. SELECT_CIS ("language=ada & type=abstraction"); -- This will return a set of CI ids that have both these properties. -- Suppose that the set returned contained: list 1, list 2, list 3, -- set 1, set 1.1.1, set 1.1.2, and stack 1. -- (The user could also have done a LIST_CIS; to see the names of -- the CIs in the catalog if there weren't too many.) LIST_VERSIONS ("list"); -- lists all possible versions of the CI 'list'. There may be a -- list 1.1.1 that is a list of one particular item which did -- not fit the 'type=abstraction' criteria. HISTORY ("list 3"); -- shows the comments recorded with each version. DESCRIBE ("list 3"); -- will show all the properties on list 3. LIST_COMPONENTS ("list 3); -- will list all the items in the version. -- Suppose that after seeing all this information the user determines -- that list 3 is the version closest to what is needed, but some -- changes need to be made. FETCH ("list 3", "list_library", "[.list_library]", update); -- This puts list 3 in the library list_library. All properties -- associated with list 3 are also copied to the library so some may -- need to be changed. -- At this point the user cannot do any more. The library can only be -- returned to the catalog by a privileged user. .EL .P This example did not show all the uses of the commands and they are described in more detail in the sections pertaining to each command. CHECK_CONSISTENCY is a command that will also be used by privileged users. Anyone is enabled to run it, but if there turn out to be any inconsistencies only a privileged user can fix them. The checks and how to fix any inconsistencies are described in the section on CHECK_CONSISTENCY. .PG .HL ^&CATALOG MANAGER COMMANDS\& .SK .HL +1 ^&CREATE_CATALOG\& .SK .P CREATE_CATALOG creates the named catalog on the system. The user must give the name as an ada identifier, and a directory name where the catalog will be placed. The directory cannot already exist, and the name of the catalog must be unique. During the creation process the user will be prompted for a password. This becomes the privileged user password, and will be prompted for before allowing anyone to perform any restricted operation. The user must also already be a documentation system user in order to run any of the catalog manager procedures. A user is added to the documentation system with ADD_USER. .LT -- CREATE_CATALOG : Create a new configuration item catalog -- 3.02-1.0 procedure CREATE_CATALOG( CATALOG_NAME : in STRING; DIRECTORY_SPEC : in STRING ); -- CATALOG_NAME : Name of the catalog to be created -- DIRECTORY_SPEC : Name of the directory to create the catalog in -- Creates a new configuration item catalog. The name of the catalog -- must be an ada identifier and the directory should not already -- exist. The user will be prompted for a privileged user password -- when the catalog is created. The user must be a document manager -- system user to be able to run this tool (see Add_User). .EL .PG .HL ^&OPEN_CATALOG\& .SK .P OPEN_CATALOG opens the specified catalog and puts the user in the interactive tool. From within the interactive tool the user can query the catalog about various CIs and fetch CIs into item libraries for modification. When the catalog is opened the user gets a read lock on the catalog. This lock prevents other users from performing operations that would change the catalog like creating a CI, but other users may also open the catalog to read it. If someone is creating a CIV in the catalog when a user tries to open it they will get a message saying that the other person has a write lock and they will be asked if they wish to override the lock. This prompt is to allow a privileged user to remove a write lock that was left on the catalog by mistake. Most users would respond no to the prompt since you must know the privileged user password to continue. If the catalog is write locked in this way when you try to open it, simply wait a few minutes and try again. If it continues to be locked by the same user for more that 30 minutes, you probably should notify a privileged user that there is a lock that may need to be removed. If the user trys to open a catalog that does not exist an error message is returned. If the user exits the interactive tool by any means other than the EXIT command their read lock will be left on the catalog. You may not re-enter the catalog is a read lock already exists for which you are the owner. This to prevent users from entering the catalog under two different login sessions because the two sessions locks would interact. For descriptions of all the interactive commands see the section on the interactive catalog manager. .LT -- OPEN_CATALOG : Open a configuration item catalog -- 3.02-1.0 procedure OPEN_CATALOG( CATALOG_NAME : in STRING ); -- CATALOG_NAME : Name of the catalog to be opened -- Opens the specified catalog and places the user in interactive -- mode. The name given must belong to an existent catalog. -- Create_Catalog should be run first if the catalog does not exist -- The user must be a document system manager user to run this tool -- (see Add_User). .EL .PG .HL ^&LIST_CATALOGS\& .SK .P LIST_CATALOGS lists all catalogs in the document manager system. If it is given a pattern to match only the catalogs with names that match the pattern will be returned. .LT -- LIST_CATALOGS : List the names of all the catalogs in the -- document system -- 3.02-1.0 procedure LIST_CATALOGS( CATALOGS : in STRING := "*" ); -- CATALOGS : Search string for the name to match -- A list of all the catalogs in the current document manager system -- is produced. The default is to list all catalogs, but a subset may -- be selected by giving a pattern to match for catalogs. The user -- must be a document manager system user to run this tool (see Add_User) .EL .PG .HL ^&CHECK_CONSISTENCY\& .SK .P CHECK_CONSISTENCY checks that the internal structure of the catalog is not corrupted and that the index of properties is correct. Any inconsistencies are reported in the file returned. The checks that it performs are as follows. .P For the catalog it checks that there is only one password, and it reports any users that have read or write locks on the catalog. If this procedure is run late at night any locks found may need to be removed with REMOVE_LOCK. If there is more than one password just redo the CHANGE_PASSWORD, but you do have to remember what the old password was. .P The index is also checked to make sure that the data node for each keyword still exists. If the node has somehow been deleted you cannot automatically recreate the data, but redefining the keyword will put the data node back. Once that is done you can run CHECK_CONSISTENCY again and do a MODIFY_PROPERTY for all the CIVs that report that the property is missing from the index. .P It checks that for each CI version in the catalog the node that contains the file components exists if the CIV has not been deleted. If the CIV has been deleted it checks that the node containing the components does not exist. In the first case where the file components do not exist an incomplete store would be the most likely cause. The solution is to delete the version with the mode being FIX_UP, and then to re-STORE or re-CREATE_CI the version. In the case of a re-STORE determining the library to store can be done by doing a LIST_LIBRARY of the libraries owned by the person that has the version fetched (which is also reported for each version). The library will still exist since it it only deleted after the CI version is completely created. If the node still exists after the CIV was supposed to be deleted , simply re-try the DELETE. .P There is a check to make sure that every CI has at least one version. If this is not so redo the CREATE_CI to fix the problem. .P In addition, this procedure will check that all the properties for each CI version are recorded in the index. If a property is missing from the index it could indicate an incomplete store in which case the person is still recorded as having the version fetched, and the library still exists. In the case of an incomplete CREATE_CI there is no record of it being fetched, but the library still exists. Depending on how many properties did not get added and whether it is a STORE or CREATE_CI there are two ways to solve this problem. The first is to delete the CI version in FIX_UP mode and then to retry the STORE or CREATE_CI. The other way only works if the operation that didn't complete was a STORE. You could add each of the properties with MODIFY_PROPERTY, take the user's name off the fetched list with CANCEL and the library name, and then delete the library. index. .P This procedure checks that the actual number of branches from this version match the number stored in the attribute recording how many branches there should be. If the number of branches is more that the recorded attribute there is nothing to do since STORE takes care of fixing the attribute the next time a branch is added. The case where there are fewer branches should never happen unless someone modifies the catalog structure directly, in which case there is no way to fix it. .P All the names of people with the CI version fetched will be included in the report although these are not necessarily inconsistencies. If you determine that a name on the fetched list is incorrect then CANCEL the library in which the person had fetched that CIV. To determine the library do a LIST_LIBRARY of that person's libraries and see which one contains that CIV. .P It also checks that for each branch there is at least on trunk on the branch. If there are no trunks on a branch then you must redo the STORE. .P Since this procedure runs over the whole catalog it will take a long time to run. It probably should not be run interactively. .LT -- CHECK_CONSISTENCY : Check the consistency of the information in -- a catalog -- 3.02-1.0 procedure CHECK_CONSISTENCY( CATALOG_NAME : in STRING; OUTPUT_FILE : in STRING ); -- CATALOG_NAME : Name of the catalog to be checked -- OUTPUT_FILE : Name of the output file for the consistency report -- Produces a report of the consistency of a given catalog -- The checks include: -- Checking that the information on a CI matches the information in -- the index. -- Checking that CIs are complete. -- Checking that all the locks are current. -- Checking that there is only one password -- The user must be a document manager system user to use this tool -- (see Add_User). .EL .PG .HL -1 ^&Guide to the Interactive Catalog Manager\& .SK .P The interactive catalog manager is a system to allow users to find configuration items (CI) in a catalog, and subsequently fetch them from the catalog to modify. It has functions that give information to a user to allow identification of a particular CIV. In addition there are procedures to control the way in which CIs are taken out of the catalog and put back. There are also a few procedures that can be performed only by a privileged user who knows the catalog password. The procedures will be discussed in four section classified by the type of procedure. .HL ^&Using the Interactive Catalog Manager\& .SK .P When you enter the interactive tool using OPEN_CATALOG you are first prompted for a password. This is the password to enable you to do privileged commands. If you are not a privileged user, or just don't want to use the privileged commands even if you are, simply hit the carriage return key. As a privileged user you may run all the privileged commands in addition to the regular ones. The tool will tell you as it sets up the catalog whether you are entering as a privileged or privileged user. .HL +1 ^&Catalog Functions& .P These two functions are operations that act within the interactive tool. The first gives help about the interactive commands, and the second terminates the interactive session. .LS 0, "o" .LE HELP .LE EXIT .ELS 0 .HL ^&Query Functions& .S .P 5 There are two types of query functions. One type operates on the catalog as a whole and generally returns with a result of several CIs. The other type provides information about a particular CIV. More details about each of the commands can be found in the sections pertaining to each of them. .SK .LM +5 .HL +1 Catalog Queries .LS 0, "o" .LE SELECT_CIS .LE CLEAR_SELECTED_SET .LE PRINT_SET .LE LIST_CIS .LE LIST_KEYWORDS .LE LIST_VERSIONS .ELS 0 .HL Configuration Item Queries .LS 0, "o" .LE DESCRIBE .LE HISTORY .LE LIST_COMPONENTS .ELS 0 .LM -5 .HL -1 ^&Configuration Item Commands& .P These are commands that may be done by anyone. FETCH and CANCEL both involve item libraries, and MODIFY_PROPERTY changes information in the index. .LS 0, "o" .LE FETCH .LE CANCEL .LE MODIFY_PROPERTY .ELS 0 .HL ^&Priviledged Operations& .P These are privileged commands, and one must have entered the interactive tool as a privileged user in order to user them. DELETE and REMOVE_LOCK are fix up commands, and CREATE_CI and STORE are both CIV creation commands. .LS 0, "o" .LE CHANGE_PASSWORD .LE DEFINE_KEYWORD .LE DELETE .LE REMOVE_LOCK .LE CREATE_CI .LE STORE .ELS 0 .HL ^&Item Library Operations& .P The following command deals with item libraries. .LS 0, "o" .LE LIBRARY_MANAGER .ELS 0 .PG .HL -1 ^&INTERACTIVE COMMANDS\& .SK .HL +1 ^&HELP& .SK .P HELP prints out a general help message listing each of the catalog commands. Short descriptions are given of the commands, but for the most part additional help is given when the command in question is entered with no parameters. .LT -- SELECT_CIS : Selects a set of CIs according to the selection criteria given -- CLEAR_SELECTED_SET : Make the current selected set be the empty set. -- PRINT_SET : Print the contents of the currently selected set. -- LIST_CIS : Lists the contents of the catalog by name. -- CHANGE_PASSWORD : Changes the privileged user password. -- This is a privileged operation -- DEFINE_KEYWORD : Define a new keyword, or change the status of an -- existing one. -- This is a privileged operation -- LIST_KEYWORDS : List all the keywords and their status. -- CREATE_CI : create a new configuration item (CI) in the catalog -- STORE : Store a new version of an already existing CI -- FETCH : Fetch a specified CI and put it in an item library. -- CANCEL : Cancel a fetch that was made with the mode update -- DELETE : Delete a configuration item that is in the catalog. -- This is a privileged operation. -- MODIFY_PROPERTY : Modify the value associated with the given keyword -- on the specified CI -- DESCRIBE : Show the values of the given keywords -- HISTORY : Give the history of the named CI -- LIST_VERSIONS : List the versions of a named CI -- LIST_COMPONENTS : List the components of the given CI -- REMOVE_LOCK : Remove a lock that was left by a user aborting a session -- This is a privileged operation -- LIBRARY_MANAGER : Invoke the Interactive Library Manager procedure HELP; .EL .PG .HL ^&SELECT_CIS& .SK .P This procedure returns a set of CIs that match the selection criteria. To specify what to select by the user enters a selection string. Sets are determined by indicating what property the CIVs should match, and there are the operators '%&' and '%|' to provide intersection and union of the sets. .LT -- SELECT_CIS : Selects a set of CIs according to the selection -- criteria given -- 3.02-1.0 procedure SELECT_CIS( CRITERIA : in STRING ); -- CRITERIA : A string in selection syntax giving the criteria to -- select by. The operators recognized are & and |. -- Parentheses can be used to indicate precedence. & does -- intersections, and | does unions. The expressions are -- evaluated from left to right .EL .HL +1 Selection Syntax: .SK The terminals in the language are: CURRENT_SET, KEYWORD, VALUE, =, %&, %|, (, and ). CURRENT_SET is a reserved word. Parentheses can be used to indicate precedence since the operators have equal precedence. CURRENT_SET is the current selected set in the catalog. KEYWORD is a catalog keyword. It should be a known keyword and must be an Ada identifier. VALUE is the corresponding value for the keyword. It must also be an Ada identifier. .LT expr ::= expr op expr | term | (expr) term ::= KEYWORD '=' VALUE | CURRENT_SET op ::= '&' | '|' .EL .P For example, the user might specify "language = nroff %& person = john" to get all nroff documents written by john or alternatively, "language = nroff %& (person = john %| person = jane)". This would result in nroff documents by jane as well as john. .PG .HL -1 ^&CLEAR_SELECTED_SET& .SK .P After any selection the user has a current selected set which is saved in the catalog. This is the set indicated by the reserved word CURRENT_SET in the selection criteria. This procedure will make that set be the empty set. .LT -- CLEAR_SELECTED_SET : Make the current selected set be the empty set. -- 3.02-1.0 procedure CLEAR_SELECTED_SET; .EL .PG .HL ^&PRINT_SET& .SK .P This prints out the CI ids of each CIV in the current selected set upon request. In this way a user can, at any time, see what has been selected even if the select was performed many commands before. .LT -- PRINT_SET : Print the contents of the currently selected set. -- 3.02-1.0 procedure PRINT_SET; .EL .PG .HL ^&LIST_CIS& .SK .P At any point the user can use this procedure to get a listing of the names of the CIs in the catalog. It will not include information about different versions of a CI, for that the user must use LIST_VERSIONS. To limit the list the user can specify a string to match and only CIs with names that match will be printed. .LT -- LIST_CIS : Lists the contents of the catalog by name. -- 3.02-1.0 procedure LIST_CIS( CIS : in STRING := "*" ); -- CIS : Name string to match, * matches all strings -- This will only list the name part of a configuration item id. To -- see the different versions of a CI use LIST_VERSIONS. .EL .PG .HL ^&LIST_KEYWORDS& .SK .P Lists all the possible keywords and their status. Keywords with status INVALID may only be used for look up. Any CIV being added to the catalog may not include a property with an invalid keyword. On the other hand, keywords with status REQUIRED must always be included on CIs being added to the catalog. Keywords may be defined or redefined by a privileged user using DEFINE_KEYWORD .LT -- LIST_KEYWORDS : List all the keywords and their status. -- 3.02-1.0 procedure LIST_KEYWORDS; -- The possible values for the status of a keyword are REQUIRED, -- OPTIONAL and INVALID. REQUIRED keywords mean that a property -- with that keyword must be on all libraries being stored in the -- catalog as CIs. OPTIONAL keywords mean a library with that -- property may be stored in the catalog. A library can not be -- stored with an INVALID property keyword. CIs may be selected -- by any keyword (see SELECT_CIS). .EL .PG .HL ^&LIST_VERSIONS& .SK .P LIST_VERSIONS lists all the different versions of a CI in the catalog. It will show the complete tree of trunks and branches. .LT -- LIST_VERSIONS : List the versions of a named CI -- 3.02-1.0 procedure LIST_VERSIONS( NAME : in STRING ); -- NAME : Name of the CI to list -- LIST_VERSIONS lists the versions of a CI with the same name. The -- name given should be an ada identifier. The list will be from -- oldest to newest. .EL .PG .HL ^&DESCRIBE& .SK .P DESCRIBE lists the properties on a CIV. With the default setting all properties of the named CIV will be listed. If a list is given only properties with a keyword that matches one of the patterns given will be listed. DESCRIBE does not check for undefined keywords in the keyword list since patterns can be specified. If a user does give only undefined keywords the list returned will be empty. .LT -- DESCRIBE : Show the values of the given keywords -- 3.02-1.0 subtype CI_ID is STRING; type STRING_LIST is array (POSITIVE range <>) of STRING; procedure DESCRIBE( NAME : in CI_ID; KEYWORDS : in STRING_LIST := ("*") ); -- NAME : Name of the CI to describe -- KEYWORDS : List of keywords to lookup the values of -- The default (*) matches all properties on a CI -- DESCRIBE does not list the creator or creation date see HISTORY -- for that information. .EL .PG .HL ^&HISTORY& .SK .P HISTORY prints out information about the creation of the CIV and its predecessors. For each predecessor its version, creator, creation date, and history comment are listed. This information is listed in order from the latest version of the CI to the first version with this name. The person that created or stored the CIV is also listed under the heading Submitter. The creator is the person that created the contents of the CIV in a library. .LT -- HISTORY : Give the history of the named CI -- 3.02-1.0 subtype CI_ID is STRING; procedure HISTORY( NAME : in CI_ID ); -- NAME : Name of the CI of which to give the history -- The history of a CI is the history comments stored when each of its -- predecessors was stored. The comments will be printed out in -- reverse order, that is, from the most recent version to the first -- version of the CI with that name. .EL .PG .HL ^&LIST_COMPONENTS& .SK .P This procedure will list the file components of the given CIV. These files, however, cannot be manipulated through the catalog manager. To do that use FETCH and then the Item Library Manager. .LT -- LIST_COMPONENTS : List the components of the given CI -- 3.02-1.0 subtype CI_ID is STRING; procedure LIST_COMPONENTS( NAME : in CI_ID ); -- NAME : Name of the CI to list -- The listing will consist of the file items that make up the -- CI. It will be in the same format as a component list from -- the Item Library Manager .EL .PG .HL ^&FETCH& .SK .P This procedure fetches a CIV into an item library for the user. If it is fetched for update there is a check to make sure that the update may be done. Once in the library the user may modify the contents using item library manager which is detailed in another section. To fetch a CIV the name parameter must be a valid CI id and must belong to an existent CIV in this catalog. The default mode for FETCH is no_update. When a fetch is done any properties on the CIV are also transferred to the item library. These may need to be changed, especially if any keywords have been made invalid since it was last stored. In no_update mode no changes made to a library can be put back in the catalog as a new version of this CI. It can be entered into the catalog as a new CIV (see CREATE_CI). If a CIV is fetched with a mode of update or branch, then it must be returned to the catalog with the STORE command or the FETCH can be erased with the CANCEL command. DELETE_LIBRARY will not allow a library to be deleted while it is still pending from a catalog. .LT -- FETCH : Fetch a specified CI and put it in an item library. -- 3.02-1.0 subtype CI_ID is STRING; type FETCH_TYPE is (NO_UPDATE, UPDATE, BRANCH); procedure FETCH( NAME : in CI_ID; LIBRARY : in STRING; DIRECTORY : in STRING; MODE : in FETCH_TYPE := NO_UPDATE ); -- NAME : Name of the ci to fetch -- LIBRARY : Name of the item library to put the CI in -- DIRECTORY : Name of the directory to create the itemlibrary in -- MODE : Indicates what type of update the fetch is allowing -- FETCH will put a specified CI in an item library for the user. -- If the mode is UPDATE or BRANCH the user can modify the CI and -- STORE it as a new version. If the mode is NO_UPDATE (default) -- the user is still free to modify the library, but it may NOT be -- returned to the catalog as a new version. When a CI is fetched -- for UPDATE checks are made to make sure that no one else is -- updating the same CI .EL .PG .HL ^&CANCEL& .SK .P CANCEL changes the mode on the library to be no_update and deletes the user's name from the list of users updating the CIV. The default for user is the current user. Only a privileged user may cancel a FETCH done by someone else, but you may cancel any of your own fetches. If this procedure is run on a library that was not fetched for update or branch it has no effect. .LT -- CANCEL : Cancel a FETCH that was made with the mode update -- 3.02-1.0 procedure CANCEL( LIBRARY : in STRING; USER : in STRING := "CHRIS" ); -- LIBRARY : Name of the item library the fetched CI is in -- USER : Name of the person who did the fetch -- Default is the current user -- Any user can cancel a FETCH that he or she made, but only a -- privileged user may cancel someone else's. So if the name given -- does not match the current user the catalog password will be -- asked for. .EL .PG .HL ^&MODIFY_PROPERTY& .SK .P This allows a user to update the properties on a CIV. If the properties on a CIV are wrong in some way or inconsistent a user may change them, but a user cannot delete a property that is required. .LT -- MODIFY_PROPERTY : Modify the value associated with the given keyword -- on the specified CI -- 3.02-1.0 subtype CI_ID is STRING; procedure MODIFY_PROPERTY( NAME : in CI_ID; KEYWORD : in STRING; VALUE : in STRING ); -- NAME : Name of the CI with the property to be changed -- KEYWORD : name of the keyword to change the value of -- VALUE : New value for the keyword -- Modify_property will change the value associated with a keyword -- on a CI. The property can not be added if the keyword is -- invalid and a property can not be removed if it is required. -- To remove a property simply give it a null string for a new -- value. This change has no effect on other CIs with the same -- name. .EL .PG .HL ^&CHANGE_PASSWORD\& .SK .P CHANGE_PASSWORD will allow a privileged user to change the catalog password. The user is prompted for first the old password and then the new one. The new password is then asked for again so that it can be verified. This procedure will fail if either the old password is incorrect or the two new passwords do not match. .LT -- CHANGE_PASSWORD : Changes the privileged user password. -- This is a privileged operation -- 3.02-1.0 procedure CHANGE_PASSWORD; -- To change the password the user must know the old password. -- The user will prompted for the old password and then the new -- password twice to verify that it was typed correctly. .EL .PG .HL ^&DEFINE_KEYWORD\& .SK .P DEFINE_KEYWORD is used to define or change the definition of keywords for the catalog. Each catalog must have its own set of keywords. A keyword can be defined with one of three different status, OPTIONAL, REQUIRED, and INVALID. If a keyword is defined as invalid it prevents libraries with that property from being added to the catalog Required keywords are keywords that must be present for a library to be added to the catalog. If any of the set of required keywords is missing the STORE or CREATE_CI will fail. Invalid keywords are still useful for looking up a CIV as a select can be done using invalid keywords. .LT -- DEFINE_KEYWORD : Define a new keyword, or change the status of an -- existing one. -- This is a privileged operation -- 3.02-1.0 type PROPER_STATUS is (OPTIONAL, REQUIRED, INVALID); procedure DEFINE_KEYWORD( KEYWORD : in STRING; STATUS : in PROPER_STATUS := OPTIONAL ); -- KEYWORD : name of the keyword to define -- STATUS : status of the keyword -- Keywords are defined so that information about CIs can be stored -- in the database. A required keyword must always be included on -- any CI stored. Optional keywords are just that, optional. -- Invalid keywords are ones that may at one time have been valid, -- but can no longer be used to store CIs. They can still be used -- for lookup since CIs added with a keyword before it was made -- invalid are not changed. .EL .PG .HL ^&DELETE\& .SK .P A CIV that is already in the catalog can be deleted using this subprogram. There are two types of DELETE, CLEAN_UP and FIX_UP, which serve different purposes. A DELETE that is being done to clean up the catalog is removing old CIs so that space can be reclaimed. A CIV that is being deleted for fix up purposes was not stored correctly in the catalog. A STORE (or CREATE_CI) can be incomplete if the user aborted in the middle or the machine crashed, so DELETE allows the incomplete CIV to be removed. The difference between the two modes is that in clean up mode the catalog manager checks there is no one with the CIV fetched, and it fails if there is someone with it fetched. Obviously, if fix up mode is fixing a STORE that was incomplete the CIV will appear to be fetched so the check is not done. .LT -- DELETE : Delete a configuration item that is in the catalog. -- This is a privileged operation. -- 3.02-1.0 subtype CI_ID is STRING; type DELETE_TYPE is (FIX_UP, CLEAN_UP); procedure DELETE( NAME : in CI_ID; MODE : in DELETE_TYPE := CLEAN_UP ); -- NAME : Name of the configuration item to delete -- MODE : What type of delete is to be done -- There are two types of deletion that may take place. Deletion of a -- CI that is out of date and not needed, and deletion of a CI where -- the STORE only partially completed for some reason. The former is -- clean_up and the latter is fix_up. When cleaning up, the catalog -- manager checks that the CI is not currently fetched. In fix up the -- STORE was incomplete and so by definition the CI will still appear -- to be fetched. .EL .PG .HL ^&REMOVE_LOCK\& .SK .P This procedure removes a lock on the catalog. Before removing any locks like this the privileged user should be sure that the lock is not current. A lock can be left behind if the user exits the catalog by any means other than the DONE command. Read locks will prevent any other user from doing any commands involving a write lock, and a write lock will prevent any user from opening the catalog. An error message is returned if the lock does not exist. .LT -- REMOVE_LOCK : Remove a lock that was left by a user aborting a session -- This is a privileged operation -- 3.02-1.0 type LOCK_TYPE is (READ, WRITE); type NODE_TYPE is (CATALOG_NODE, CI_NODE, INDEX_NODE); procedure REMOVE_LOCK( NAME : in STRING; LOCK : in LOCK_TYPE; NODE_NAME : in STRING := "current_catalog"; NODE : in NODE_TYPE := CATALOG_NODE ); -- NAME : Name of the person owning the lock -- LOCK : Type of lock that is to be removed -- NODE_NAME : Name of the node to be unlocked -- NODE : Type of node to be unlocked .EL .PG .HL ^&CREATE_CI& .SK .P This procedure is used to create a new CI in the catalog. During creation checks will be done before any real changes are made. In this way nothing in the catalog will be changed unless there are no errors. As many errors as can be found will be reported before finishing execution enabling a user to fix up all of the known errors before proceeding. To create a CI, the library must not have been fetched for update or branch; the name must be unique and an ada identifier; it must include all required keywords, and may not include any keywords that are invalid or undefined. This is a privileged operation that should probably be controlled by a CM coordinator. .LT -- CREATE_CI : create a new configuration item (CI) in the catalog -- 3.02-1.0 subtype CI_ID is STRING; procedure CREATE_CI( NAME : in CI_ID; LIBRARY : in STRING; HISTORY : in STRING ); -- NAME : Name of the new ci to create -- LIBRARY : Name of the item library to create the CI from -- HISTORY : Brief description of the new CI -- Any errors encountered will be reported to the user and the -- creation will not take place. In addition to having the correct -- status, the keywords on the library must be both valid, and -- include all the required ones. The history parameter will be -- stored on the new CI along with the creator and date. This -- information can be seen with the HISTORY command. .EL .PG .HL ^&STORE& .SK .P STORE is similar to create, but it creates a new CIV which is based on an old one instead of an entirely new CI. It checks for slightly different errors, but like CREATE_CI as many errors as can be found will be reported and the STORE will not take place if there are any errors. To STORE a library, it must have been fetched for update or branch; the owner of the library must be the user that did the FETCH; the CIV this library is based on must exist in this catalog; the CI name must be a valid ada identifier; the properties must include all required keywords, and not include any that are invalid. This is also a privileged operation. .LT -- STORE : Store a new version of an already existing CI -- 3.02-1.0 procedure STORE( LIBRARY : in STRING; HISTORY : in STRING ); -- LIBRARY : Name of the item library to get the CI from -- HISTORY : Description of the changes made to the new CI -- Any errors encountered will be reported to the user and the -- STORE will not take place. In addition to being fetched -- correctly, the keywords on the library must be both valid, -- and include all the required ones. The history parameter will -- be stored along with the creator and date and can be accessed -- with the history command. .EL .PG .HL ^&LIBRARY_MANAGER& .SK .P Refer to the section on Interactive Library Manager for command description and syntax. :::::::::::::: docfile :::::::::::::: :::::::::::::: docmgr.cnt :::::::::::::: USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CREATERM.ADA 7 L 0 C 4 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]DOCMGR.DAT 13 L 4 C 3 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]ADDUSER.ADA 91 L 0 C 44 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]DELHUSER.SPC 15 L 5 C 4 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]DELHUSER.BDY 60 L 3 C 29 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]DELUSER.ADA 34 L 0 C 19 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]PAGINATE.ADA 238 L 1 C 117 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LIBMGR.DAT 140 L 53 C 69 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LIBERR.SPC 56 L 4 C 6 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LIBERR.BDY 135 L 3 C 34 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LIBUTL.SPC 599 L 216 C 57 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LIBUTL.BDY 2179 L 5 C 116 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]ADDP.SPC 19 L 5 C 6 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]ADDP.BDY 123 L 0 C 74 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CANCELI.SPC 16 L 5 C 4 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CANCELI.BDY 100 L 0 C 60 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]COPYL.SPC 22 L 7 C 5 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]COPYL.BDY 167 L 0 C 103 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]COPYL.ADA 103 L 0 C 41 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CREATEI.SPC 18 L 6 C 4 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CREATEI.BDY 117 L 0 C 72 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CREATEI.ADA 83 L 0 C 35 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CREATEL.SPC 16 L 5 C 4 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CREATEL.BDY 88 L 0 C 52 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CREATEL.ADA 69 L 0 C 31 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]DELETEI.SPC 19 L 5 C 6 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]DELETEI.BDY 130 L 0 C 82 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]DELETEL.SPC 17 L 5 C 6 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]DELETEL.BDY 91 L 0 C 53 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]DELETEL.ADA 60 L 0 C 29 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]DELETEP.SPC 18 L 5 C 6 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]DELETEP.BDY 113 L 0 C 68 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]FETCHI.SPC 22 L 7 C 5 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]FETCHI.BDY 208 L 0 C 136 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]FETCHI.ADA 106 L 0 C 43 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LISTI.SPC 21 L 6 C 5 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LISTI.BDY 174 L 0 C 113 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LISTI.ADA 107 L 0 C 43 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LISTL.SPC 16 L 5 C 4 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LISTL.BDY 121 L 0 C 80 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LISTL.ADA 69 L 0 C 30 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LISTP.SPC 18 L 7 C 4 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LISTP.BDY 134 L 0 C 85 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]MODIFYP.SPC 20 L 6 C 6 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]MODIFYP.BDY 123 L 0 C 74 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]PURGEI.SPC 18 L 5 C 6 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]PURGEI.BDY 104 L 0 C 60 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]RENAMEI.SPC 19 L 5 C 6 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]RENAMEI.BDY 115 L 0 C 66 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]RENAMEV.SPC 21 L 6 C 6 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]RENAMEV.BDY 129 L 0 C 74 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]RETURNI.SPC 18 L 6 C 4 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]RETURNI.BDY 118 L 0 C 73 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]RETURNI.ADA 79 L 0 C 35 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]SHOWHIST.SPC 18 L 6 C 4 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]SHOWHIST.BDY 174 L 0 C 112 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LIBMGR.SPC 16 L 5 C 4 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LIBMGR.BDY 956 L 65 C 255 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LIBMGR.ADA 69 L 0 C 31 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]VLIST.SPC 2 L 0 C 2 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CIID.SPC 216 L 77 C 31 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CATDECLS.DAT 30 L 2 C 19 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]PROP.SPC 29 L 0 C 11 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]PROP.BDY 27 L 0 C 8 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CATMGR.SPC 380 L 196 C 66 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CIID.BDY 535 L 123 C 158 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]HIFUTIL.SPC 37 L 2 C 9 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LOCK.SPC 64 L 27 C 12 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CIINDEX.SPC 149 L 62 C 27 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CIINDEX.BDY 424 L 97 C 166 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CATMGR.BDY 1646 L 256 C 747 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]RDPARSER.SPC 67 L 11 C 26 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]COMMAND.SPC 12 L 5 C 2 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]COMMAND.BDY 1224 L 75 C 613 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]HIFUTIL.BDY 61 L 2 C 19 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]INTERFACE.SPC 123 L 82 C 7 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]INTERFACE.BDY 609 L 77 C 150 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LOCK.BDY 243 L 72 C 93 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]RDPARSER.BDY 157 L 11 C 79 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CHCONSIST.ADA 112 L 23 C 39 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]LISTCAT.ADA 71 L 10 C 27 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]CREATECAT.ADA 88 L 17 C 31 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]OPENCAT.ADA 77 L 15 C 28 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]FGEN.BDY 873 L 97 C 354 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]FGEN.SPC 15 L 0 C 5 S USER1:[NOSC.RELEASES.V0302.DOCMGR.SOURCE]FILEGEN.ADA 94 L 5 C 32 S :::::::::::::: docmgr.mem :::::::::::::: Documentation System User Guide ____________ INTRODUCTION The Documentation System is made up of four parts: the catalog manager; the item library manager; paginate and filegen. The catalog manager is the interface to configuration item catalogs, and the item library manager is the interface to item libraries. These interfaces will be described in detail in later sections, although some commands will be mentioned here to provide an overview of the system. Filegen and paginate are utilities to be used with the Documentation System. ________ _ _____________ ______ ____ BECOMING A DOCUMENTATION SYSTEM USER In order to use the Documentation System the user must be a HIF user. There is an operation ADD_USER that will make a user a HIF user. ADD_USER has two parameters: a directory where HIF data files will be kept and a user id. The user id defaults to the current user id. If you are adding yourself there is no need to specify the second parameter. In order to be recognized as a HIF user your HIF user id must be the same as your login id. In addition to ADD_USER there is DELETE_USER that takes no parameters and removes the current user from the HIF. The user must also set two logical variables called HIF_DIRECTORY and HIF_FDL. This is best done at login time. The values for both of these variables are determined at installation time by the person that sets up the documentation system. All operations will fail if the user is not a HIF user. ________ __ ___ _______ _______ ___ ____ _______ _______ OVERVIEW OF THE CATALOG MANAGER AND ITEM LIBRARY MANAGER A configuration item (CI) is a collection of files that are logically connected. For example the set of files that make up a list package could be grouped as one CI. The user has the option of including all files, source and documentation, in one CI or dividing the files into one or more CIs as seems appropriate. The degenerate case would be where a CI contains only one item. The way in which the files are grouped prior to making them a CI is to put them into an item library. An item is not a file. It is the 'contents' of that file. In this way an item library can contain any number of versions of one 'item'. Item libraries are created with the item library manager command CREATE_LIBRARY. A library is created empty and your files are put into the library with the command CREATE_ITEM. More versions of an item are created by calling FETCH_ITEM, modifying the file and then calling RETURN_ITEM. In order to make a CI there must be a catalog in which to put it. Catalogs are created with the CREATE_CATALOG command. Any number of catalogs can be in the same documentation system, but they must have unique names. Different projects may want to keep Documentation System User Guide Page 2 their CIs in different catalogs. There are three other commands that act on catalogs: LIST_CATALOGS, CHECK_CONSISTENCY and OPEN_CATALOG. LIST_CATALOGS will list all catalogs in the documentation system; CHECK_CONSISTENCY walks a catalog structure reporting any inconsistencies; OPEN_CATALOG is an interactive tool that provides the user interface to CIs in a catalog. Any commands following that deal with CIs are actually commands within the OPEN_CATALOG tool. To make a CI you must have an item library. A CI is made from the library when you execute the command CREATE_CI. At this time the contents of the library are put into the catalog under the name that you give it and the library is deleted. For example, suppose the list package files were put into a library, now they are in a controlled environment for the developer to modify and test the code until a working list package is arrived at. The user should then let a configuration management (CM) coordinator know which library to take. Using CREATE_CI the CM coordinator will make a CI from the specified library. CREATE_CI takes the most recent version of each item, and other information stored in the library moves it into the catalog under the name given to CREATE_CI which might have been 'list' for the list package. A CI version of '1' will be assigned to this CI and so the CI id of this CI version is 'list 1'. Although there are versions of a CI, each version could be viewed as a configuration item itself. This is easy to understand since each 'version' exists for some reason, and even though new development would probably use the most current version of any CI it needs, there will undoubtedly be something that still depends on an older version, So to avoid confusion, from now on 'CI' will refer to the complete collection of versions that share the same CI name, and 'CI version' (CIV) will refer to a particular instance of a CI. A CI id identifies a particular CI version. When a CIV is put into the catalog other information in addition to the files is kept. Properties are part of the information taken from the library. A property is a keyword, value pair that identifies some attribute of the CIV. For example the list package might have a property: LANGUAGE-ADA. Properties are attached to a CIV when it is in the item library stage. There are item library commands to add, delete and change properties. The properties are not checked, however, until the user tries to make the library a CIV. The reason for this is that different catalogs can have different sets of valid keywords and when you just have an item library there is nothing to determine which catalog in which it may be put later. The valid keywords for a catalog are defined by a privileged user, usually the person that created the catalog, and keywords can be defined to be required on every CIV. When the CIV is created or stored in the catalog its properties are checked to make sure they all have valid keywords and all the required ones are included. Then the properties are stored in a database that allows users to query the catalog by properties. Documentation System User Guide Page 3 Having determined through the database what CIV they want a user can FETCH it to modify or just to use. When a CIV is fetched its contents are put into a specified item library. At this point the user may fetch and return items as before, and the item library in this case can be thought of as a working copy of the CI. When the library is again ready to become a CIV it is returned to the catalog with the STORE operation. The store operation will give the CIV a CI id that has the same CI name as before and the next number sequentially for the version. For example, suppose a user wanted to add a labeled list to the list package. The CIV could be fetched, modified and then stored. It would have a CI id of 'list 2'. This development cycle can be repeated any number of times. The user should note that CREATE_CI and STORE are privileged commands that can only be executed by a person that knows the catalog password. This would normally be the person that created the catalog or a CM coordinator. On the other hand any user may do a FETCH and most of the other commands in the interactive tool. ________ ___ _______ PAGINATE AND FILEGEN Paginate and Filegen are utilities that can be used with the catalog manager and the item library manager, or independently. Paginate will produce an output file with page breaks , a header and a footer from any text input file. The options it allows are described fully in the paginate section. Filegen is a file inclusion utility. Given a file containing filegen directives it will produce an output file that contains the original file's text, the text of any files included and other information like the current date and the CI name of the CIV the file is in. The information that can be included is described in detail in the filegen section dealing with the filegen directives. In addition to being able to include other files from your file system, you can include files from a library or even a CIV in a catalog. You can also produce output from a file inside a CIV. If you give as input the name of an item in a CIV, the the CIV's CI id and the catalog name, file gen will produce an output file that is the text of the input item, and the information generated by the filegen directives. Documentation System User Guide Page 4 _______ _______ CATALOG MANAGER ___________ Description A catalog is a database of configuration items (CI), and the catalog manager encompasses the procedures that allow users to manage catalogs, access CIs and add new CIs. A catalog contains CIs, a keyword list and a property index. CIs will have properties to describe them, and when a CI is added to the catalog its properties are stored in the index so it can be referenced by property. A property is a keyword, value pair, and all the allowable keywords for the catalog are stored in its keyword list. There are three states that a keyword can have: optional, required and invalid. Invalid keywords are ones that once were valid. Libraries can only be STORED into the catalog as a CI version if all the properties are valid. In this way a user can use an invalid keyword when selecting CIVs from the index since there may be versions that were added to the catalog before the keyword was invalid. Although it is possible to define a keyword as invalid from the start it serves no useful purpose. There are four procedures that act on catalogs. CREATE_CATALOG creates new catalogs, and any number of catalogs can be created as long as they have unique names. A catalog name must be an Ada identifier. LIST_CATALOGS will list all the catalogs in the system. It can be given a pattern in which case it will only print out those catalogs whose name matches the pattern. OPEN_CATALOG will open a specific catalog and put the user in an interactive tool where he can select CIVs, fetch and store them. In the interactive tool the user can also print out various information stored in the catalog about the CIVs. CHECK_CONSISTENCY will read the structure of a catalog and the information in it and check that it is not corrupt. It will report any inconsistencies it finds. It does not do any actual fixing, but there are ways for privileged users to fix the inconsistencies. _____________ ____ ________ Configuration Item Versions A CI version will have file components and properties. The file components are the source files that go into making up the version. A file component can be any type of text; code or documentation. Properties are keyword, value pairs associated with a version that describe it in some way. For example, a keyword might be subject, and a value for that keyword might be ADA_pdl. Both keywords and values must be ada identifiers. When an item library is added to a catalog to become a CIV its properties must have keywords that are valid for that catalog, and they must include all required keywords. If there are any errors when a library is being added to the catalog, the error is reported and the library is left where it is. Item libraries are managed by the Item Library Manager procedures. Documentation System User Guide Page 5 _____________ ______________ Configuration Identification A CI id consists of two parts, a name which is an ada identifier and the version which is assigned by the catalog manager. The version is a number beginning at 1 with the version being assigned sequentially. If a CIV is only fetched for update then its versions will be a single number. The updates of a CI are called trunk versions. When a CIV is fetched as a branch the version gets two more numbers when it is stored. The first number indicates what branch this is and then the second indicates that this CIV is the first version along the branch. For example, a branch from the CIV 'example 2' would be given the CI id 'example 2.1.1' when it was stored. This new CIV can also be checked out for updating, and when the store is done the CI id would be 'example 2.1.2'. These CIVs begin a trunk along the branch. It is also possible to have branches from branches. For example, the STORE of a branch from 'example 2.1.2' would be given a CI id of 'example 2.1.2.1.1'. It should be noted that in addition to making the version numbers longer, branches add some computational overhead, so operations with branches will take a little longer depending on how many levels of branching there is. _____ ___ _______ _______ Using The Catalog Manager A project should set up a catalog in which to put its CIs. When CREATE_CATALOG is invoked the user must supply a directory where the catalog will keep its data files. The catalog directory is like an Ada program library: you may go into it and list the files, but if you change anything you may corrupt the catalog beyond repair. It is suggested that the project create one directory for catalog related file and create the catalog as a subdirectory of the designated directory. The user directories and item libraries can also be subdirectories of this directory enabling a backup of all documentation system data to be collected easily. When the catalog is created a password is prompted for. This password should then only be given out to those that NEED to know like a CM coordinator. The only command that changes the catalog which is not privileged is MODIFY_PROPERTY, but it only affects the index. Once the catalog is created the creator should lose no time in opening it and defining the keywords allowed and add any item libraries pending. _______ _______ Example Session A user beginning to use the system for the first time would probably execute a sequence of commands like the following: LIST_CATALOGS; -- to find out what catalogs are available. -- Suppose there was a catalog called "PROJECT" that is the user's -- project catalog. OPEN_CATALOG ("PROJECT"); -- opens the catalog. -- Note that the names are Ada identifiers so case is unimportant. Documentation System User Guide Page 6 LIST_KEYWORDS; -- lists the possible keywords to select by. -- Suppose that there are keywords language, type, subject, -- implementor, group, and that the user is interested in finding -- the list package mentioned earlier with the requirement that -- it be written in Ada. SELECT_CIS ("language=ada & type=abstraction"); -- This will return a set of CI ids that have both these properties. -- Suppose that the set returned contained: list 1, list 2, list 3, -- set 1, set 1.1.1, set 1.1.2, and stack 1. -- (The user could also have done a LIST_CIS; to see the names of -- the CIs in the catalog if there weren't too many.) LIST_VERSIONS ("list"); -- lists all possible versions of the CI 'list'. There may be a -- list 1.1.1 that is a list of one particular item which did -- not fit the 'type=abstraction' criteria. HISTORY ("list 3"); -- shows the comments recorded with each version. DESCRIBE ("list 3"); -- will show all the properties on list 3. LIST_COMPONENTS ("list 3); -- will list all the items in the version. -- Suppose that after seeing all this information the user determines -- that list 3 is the version closest to what is needed, but some -- changes need to be made. FETCH ("list 3", "list_library", "[.list_library]", update); -- This puts list 3 in the library list_library. All properties -- associated with list 3 are also copied to the library so some may -- need to be changed. -- At this point the user cannot do any more. The library can only be -- returned to the catalog by a privileged user. This example did not show all the uses of the commands and they are described in more detail in the sections pertaining to each command. CHECK_CONSISTENCY is a command that will also be used by privileged users. Anyone is enabled to run it, but if there turn out to be any inconsistencies only a privileged user can fix them. The checks and how to fix any inconsistencies are described in the section on CHECK_CONSISTENCY. Documentation System User Guide Page 7 _______ _______ ________ CATALOG MANAGER COMMANDS ______________ CREATE_CATALOG - CREATE_CATALOG creates the named catalog on the system. The user must give the name as an ada identifier, and a directory name where the catalog will be placed. The directory cannot already exist, and the name of the catalog must be unique. During the creation process the user will be prompted for a password. This becomes the privileged user password, and will be prompted for before allowing anyone to perform any restricted operation. The user must also already be a documentation system user in order to run any of the catalog manager procedures. A user is added to the documentation system with ADD_USER. -- CREATE_CATALOG : Create a new configuration item catalog -- 3.02-1.0 procedure CREATE_CATALOG( CATALOG_NAME : in STRING; DIRECTORY_SPEC : in STRING ); -- CATALOG_NAME : Name of the catalog to be created -- DIRECTORY_SPEC : Name of the directory to create the catalog in -- Creates a new configuration item catalog. The name of the catalog -- must be an ada identifier and the directory should not already -- exist. The user will be prompted for a privileged user password -- when the catalog is created. The user must be a document manager -- system user to be able to run this tool (see Add_User). Documentation System User Guide Page 8 ____________ OPEN_CATALOG - OPEN_CATALOG opens the specified catalog and puts the user in the interactive tool. From within the interactive tool the user can query the catalog about various CIs and fetch CIs into item libraries for modification. When the catalog is opened the user gets a read lock on the catalog. This lock prevents other users from performing operations that would change the catalog like creating a CI, but other users may also open the catalog to read it. If someone is creating a CIV in the catalog when a user tries to open it they will get a message saying that the other person has a write lock and they will be asked if they wish to override the lock. This prompt is to allow a privileged user to remove a write lock that was left on the catalog by mistake. Most users would respond no to the prompt since you must know the privileged user password to continue. If the catalog is write locked in this way when you try to open it, simply wait a few minutes and try again. If it continues to be locked by the same user for more that 30 minutes, you probably should notify a privileged user that there is a lock that may need to be removed. If the user trys to open a catalog that does not exist an error message is returned. If the user exits the interactive tool by any means other than the EXIT command their read lock will be left on the catalog. You may not re-enter the catalog is a read lock already exists for which you are the owner. This to prevent users from entering the catalog under two different login sessions because the two sessions locks would interact. For descriptions of all the interactive commands see the section on the interactive catalog manager. -- OPEN_CATALOG : Open a configuration item catalog -- 3.02-1.0 procedure OPEN_CATALOG( CATALOG_NAME : in STRING ); -- CATALOG_NAME : Name of the catalog to be opened -- Opens the specified catalog and places the user in interactive -- mode. The name given must belong to an existent catalog. -- Create_Catalog should be run first if the catalog does not exist -- The user must be a document system manager user to run this tool -- (see Add_User). Documentation System User Guide Page 9 _____________ LIST_CATALOGS - LIST_CATALOGS lists all catalogs in the document manager system. If it is given a pattern to match only the catalogs with names that match the pattern will be returned. -- LIST_CATALOGS : List the names of all the catalogs in the -- document system -- 3.02-1.0 procedure LIST_CATALOGS( CATALOGS : in STRING := "*" ); -- CATALOGS : Search string for the name to match -- A list of all the catalogs in the current document manager system -- is produced. The default is to list all catalogs, but a subset may -- be selected by giving a pattern to match for catalogs. The user -- must be a document manager system user to run this tool (see Add_User) Documentation System User Guide Page 10 _________________ CHECK_CONSISTENCY - CHECK_CONSISTENCY checks that the internal structure of the catalog is not corrupted and that the index of properties is correct. Any inconsistencies are reported in the file returned. The checks that it performs are as follows. For the catalog it checks that there is only one password, and it reports any users that have read or write locks on the catalog. If this procedure is run late at night any locks found may need to be removed with REMOVE_LOCK. If there is more than one password just redo the CHANGE_PASSWORD, but you do have to remember what the old password was. The index is also checked to make sure that the data node for each keyword still exists. If the node has somehow been deleted you cannot automatically recreate the data, but redefining the keyword will put the data node back. Once that is done you can run CHECK_CONSISTENCY again and do a MODIFY_PROPERTY for all the CIVs that report that the property is missing from the index. It checks that for each CI version in the catalog the node that contains the file components exists if the CIV has not been deleted. If the CIV has been deleted it checks that the node containing the components does not exist. In the first case where the file components do not exist an incomplete store would be the most likely cause. The solution is to delete the version with the mode being FIX_UP, and then to re-STORE or re-CREATE_CI the version. In the case of a re-STORE determining the library to store can be done by doing a LIST_LIBRARY of the libraries owned by the person that has the version fetched (which is also reported for each version). The library will still exist since it it only deleted after the CI version is completely created. If the node still exists after the CIV was supposed to be deleted , simply re-try the DELETE. There is a check to make sure that every CI has at least one version. If this is not so redo the CREATE_CI to fix the problem. In addition, this procedure will check that all the properties for each CI version are recorded in the index. If a property is missing from the index it could indicate an incomplete store in which case the person is still recorded as having the version fetched, and the library still exists. In the case of an incomplete CREATE_CI there is no record of it being fetched, but the library still exists. Depending on how many properties did not get added and whether it is a STORE or CREATE_CI there are two ways to solve this problem. The first is to delete the CI version in FIX_UP mode and then to retry the STORE or CREATE_CI. The other way only works if the operation that didn't complete was a STORE. You could add each of the properties with MODIFY_PROPERTY, take the user's name off the fetched list with CANCEL and the library name, and then delete the library. index. Documentation System User Guide Page 11 This procedure checks that the actual number of branches from this version match the number stored in the attribute recording how many branches there should be. If the number of branches is more that the recorded attribute there is nothing to do since STORE takes care of fixing the attribute the next time a branch is added. The case where there are fewer branches should never happen unless someone modifies the catalog structure directly, in which case there is no way to fix it. All the names of people with the CI version fetched will be included in the report although these are not necessarily inconsistencies. If you determine that a name on the fetched list is incorrect then CANCEL the library in which the person had fetched that CIV. To determine the library do a LIST_LIBRARY of that person's libraries and see which one contains that CIV. It also checks that for each branch there is at least on trunk on the branch. If there are no trunks on a branch then you must redo the STORE. Since this procedure runs over the whole catalog it will take a long time to run. It probably should not be run interactively. -- CHECK_CONSISTENCY : Check the consistency of the information in -- a catalog -- 3.02-1.0 procedure CHECK_CONSISTENCY( CATALOG_NAME : in STRING; OUTPUT_FILE : in STRING ); -- CATALOG_NAME : Name of the catalog to be checked -- OUTPUT_FILE : Name of the output file for the consistency report -- Produces a report of the consistency of a given catalog -- The checks include: -- Checking that the information on a CI matches the information in -- the index. -- Checking that CIs are complete. -- Checking that all the locks are current. -- Checking that there is only one password -- The user must be a document manager system user to use this tool -- (see Add_User). Documentation System User Guide Page 12 _____ __ ___ ___________ _______ _______ Guide To The Interactive Catalog Manager The interactive catalog manager is a system to allow users to find configuration items (CI) in a catalog, and subsequently fetch them from the catalog to modify. It has functions that give information to a user to allow identification of a particular CIV. In addition there are procedures to control the way in which CIs are taken out of the catalog and put back. There are also a few procedures that can be performed only by a privileged user who knows the catalog password. The procedures will be discussed in four section classified by the type of procedure. _____ ___ ___________ _______ _______ Using The Interactive Catalog Manager When you enter the interactive tool using OPEN_CATALOG you are first prompted for a password. This is the password to enable you to do privileged commands. If you are not a privileged user, or just don't want to use the privileged commands even if you are, simply hit the carriage return key. As a privileged user you may run all the privileged commands in addition to the regular ones. The tool will tell you as it sets up the catalog whether you are entering as a privileged or privileged user. _______ _________ Catalog Functions These two functions are operations that act within the interactive tool. The first gives help about the interactive commands, and the second terminates the interactive session. o HELP o EXIT _____ _________ Query Functions There are two types of query functions. One type operates on the catalog as a whole and generally returns with a result of several CIs. The other type provides information about a particular CIV. More details about each of the commands can be found in the sections pertaining to each of them. Catalog Queries - o SELECT_CIS o CLEAR_SELECTED_SET o PRINT_SET o LIST_CIS o LIST_KEYWORDS o LIST_VERSIONS Configuration Item Queries - o DESCRIBE o HISTORY o LIST_COMPONENTS Documentation System User Guide Page 13 _____________ ____ ________ Configuration Item Commands These are commands that may be done by anyone. FETCH and CANCEL both involve item libraries, and MODIFY_PROPERTY changes information in the index. o FETCH o CANCEL o MODIFY_PROPERTY ___________ __________ Priviledged Operations These are privileged commands, and one must have entered the interactive tool as a privileged user in order to user them. DELETE and REMOVE_LOCK are fix up commands, and CREATE_CI and STORE are both CIV creation commands. o CHANGE_PASSWORD o DEFINE_KEYWORD o DELETE o REMOVE_LOCK o CREATE_CI o STORE ____ _______ __________ Item Library Operations The following command deals with item libraries. o LIBRARY_MANAGER Documentation System User Guide Page 14 ___________ ________ INTERACTIVE COMMANDS ____ HELP HELP prints out a general help message listing each of the catalog commands. Short descriptions are given of the commands, but for the most part additional help is given when the command in question is entered with no parameters. -- SELECT_CIS : Selects a set of CIs according to the selection criteria given -- CLEAR_SELECTED_SET : Make the current selected set be the empty set. -- PRINT_SET : Print the contents of the currently selected set. -- LIST_CIS : Lists the contents of the catalog by name. -- CHANGE_PASSWORD : Changes the privileged user password. -- This is a privileged operation -- DEFINE_KEYWORD : Define a new keyword, or change the status of an -- existing one. -- This is a privileged operation -- LIST_KEYWORDS : List all the keywords and their status. -- CREATE_CI : create a new configuration item (CI) in the catalog -- STORE : Store a new version of an already existing CI -- FETCH : Fetch a specified CI and put it in an item library. -- CANCEL : Cancel a fetch that was made with the mode update -- DELETE : Delete a configuration item that is in the catalog. -- This is a privileged operation. -- MODIFY_PROPERTY : Modify the value associated with the given keyword -- on the specified CI -- DESCRIBE : Show the values of the given keywords -- HISTORY : Give the history of the named CI -- LIST_VERSIONS : List the versions of a named CI -- LIST_COMPONENTS : List the components of the given CI -- REMOVE_LOCK : Remove a lock that was left by a user aborting a session -- This is a privileged operation -- LIBRARY_MANAGER : Invoke the Interactive Library Manager procedure HELP; Documentation System User Guide Page 15 __________ SELECT_CIS This procedure returns a set of CIs that match the selection criteria. To specify what to select by the user enters a selection string. Sets are determined by indicating what property the CIVs should match, and there are the operators '&' and '|' to provide intersection and union of the sets. -- SELECT_CIS : Selects a set of CIs according to the selection -- criteria given -- 3.02-1.0 procedure SELECT_CIS( CRITERIA : in STRING ); -- CRITERIA : A string in selection syntax giving the criteria to -- select by. The operators recognized are & and |. -- Parentheses can be used to indicate precedence. & does -- intersections, and | does unions. The expressions are -- evaluated from left to right Selection Syntax: - The terminals in the language are: CURRENT_SET, KEYWORD, VALUE, =, &, |, (, and ). CURRENT_SET is a reserved word. Parentheses can be used to indicate precedence since the operators have equal precedence. CURRENT_SET is the current selected set in the catalog. KEYWORD is a catalog keyword. It should be a known keyword and must be an Ada identifier. VALUE is the corresponding value for the keyword. It must also be an Ada identifier. expr ::= expr op expr | term | (expr) term ::= KEYWORD '=' VALUE | CURRENT_SET op ::= '&' | '|' For example, the user might specify "language = nroff & person = john" to get all nroff documents written by john or alternatively, "language = nroff & (person = john | person = jane)". This would result in nroff documents by jane as well as john. Documentation System User Guide Page 16 __________________ CLEAR_SELECTED_SET After any selection the user has a current selected set which is saved in the catalog. This is the set indicated by the reserved word CURRENT_SET in the selection criteria. This procedure will make that set be the empty set. -- CLEAR_SELECTED_SET : Make the current selected set be the empty set. -- 3.02-1.0 procedure CLEAR_SELECTED_SET; Documentation System User Guide Page 17 _________ PRINT_SET This prints out the CI ids of each CIV in the current selected set upon request. In this way a user can, at any time, see what has been selected even if the select was performed many commands before. -- PRINT_SET : Print the contents of the currently selected set. -- 3.02-1.0 procedure PRINT_SET; Documentation System User Guide Page 18 ________ LIST_CIS At any point the user can use this procedure to get a listing of the names of the CIs in the catalog. It will not include information about different versions of a CI, for that the user must use LIST_VERSIONS. To limit the list the user can specify a string to match and only CIs with names that match will be printed. -- LIST_CIS : Lists the contents of the catalog by name. -- 3.02-1.0 procedure LIST_CIS( CIS : in STRING := "*" ); -- CIS : Name string to match, * matches all strings -- This will only list the name part of a configuration item id. To -- see the different versions of a CI use LIST_VERSIONS. Documentation System User Guide Page 19 _____________ LIST_KEYWORDS Lists all the possible keywords and their status. Keywords with status INVALID may only be used for look up. Any CIV being added to the catalog may not include a property with an invalid keyword. On the other hand, keywords with status REQUIRED must always be included on CIs being added to the catalog. Keywords may be defined or redefined by a privileged user using DEFINE_KEYWORD -- LIST_KEYWORDS : List all the keywords and their status. -- 3.02-1.0 procedure LIST_KEYWORDS; -- The possible values for the status of a keyword are REQUIRED, -- OPTIONAL and INVALID. REQUIRED keywords mean that a property -- with that keyword must be on all libraries being stored in the -- catalog as CIs. OPTIONAL keywords mean a library with that -- property may be stored in the catalog. A library can not be -- stored with an INVALID property keyword. CIs may be selected -- by any keyword (see SELECT_CIS). Documentation System User Guide Page 20 _____________ LIST_VERSIONS LIST_VERSIONS lists all the different versions of a CI in the catalog. It will show the complete tree of trunks and branches. -- LIST_VERSIONS : List the versions of a named CI -- 3.02-1.0 procedure LIST_VERSIONS( NAME : in STRING ); -- NAME : Name of the CI to list -- LIST_VERSIONS lists the versions of a CI with the same name. The -- name given should be an ada identifier. The list will be from -- oldest to newest. Documentation System User Guide Page 21 ________ DESCRIBE DESCRIBE lists the properties on a CIV. With the default setting all properties of the named CIV will be listed. If a list is given only properties with a keyword that matches one of the patterns given will be listed. DESCRIBE does not check for undefined keywords in the keyword list since patterns can be specified. If a user does give only undefined keywords the list returned will be empty. -- DESCRIBE : Show the values of the given keywords -- 3.02-1.0 subtype CI_ID is STRING; type STRING_LIST is array (POSITIVE range <>) of STRING; procedure DESCRIBE( NAME : in CI_ID; KEYWORDS : in STRING_LIST := ("*") ); -- NAME : Name of the CI to describe -- KEYWORDS : List of keywords to lookup the values of -- The default (*) matches all properties on a CI -- DESCRIBE does not list the creator or creation date see HISTORY -- for that information. Documentation System User Guide Page 22 _______ HISTORY HISTORY prints out information about the creation of the CIV and its predecessors. For each predecessor its version, creator, creation date, and history comment are listed. This information is listed in order from the latest version of the CI to the first version with this name. The person that created or stored the CIV is also listed under the heading Submitter. The creator is the person that created the contents of the CIV in a library. -- HISTORY : Give the history of the named CI -- 3.02-1.0 subtype CI_ID is STRING; procedure HISTORY( NAME : in CI_ID ); -- NAME : Name of the CI of which to give the history -- The history of a CI is the history comments stored when each of its -- predecessors was stored. The comments will be printed out in -- reverse order, that is, from the most recent version to the first -- version of the CI with that name. Documentation System User Guide Page 23 _______________ LIST_COMPONENTS This procedure will list the file components of the given CIV. These files, however, cannot be manipulated through the catalog manager. To do that use FETCH and then the Item Library Manager. -- LIST_COMPONENTS : List the components of the given CI -- 3.02-1.0 subtype CI_ID is STRING; procedure LIST_COMPONENTS( NAME : in CI_ID ); -- NAME : Name of the CI to list -- The listing will consist of the file items that make up the -- CI. It will be in the same format as a component list from -- the Item Library Manager Documentation System User Guide Page 24 _____ FETCH This procedure fetches a CIV into an item library for the user. If it is fetched for update there is a check to make sure that the update may be done. Once in the library the user may modify the contents using item library manager which is detailed in another section. To fetch a CIV the name parameter must be a valid CI id and must belong to an existent CIV in this catalog. The default mode for FETCH is no_update. When a fetch is done any properties on the CIV are also transferred to the item library. These may need to be changed, especially if any keywords have been made invalid since it was last stored. In no_update mode no changes made to a library can be put back in the catalog as a new version of this CI. It can be entered into the catalog as a new CIV (see CREATE_CI). If a CIV is fetched with a mode of update or branch, then it must be returned to the catalog with the STORE command or the FETCH can be erased with the CANCEL command. DELETE_LIBRARY will not allow a library to be deleted while it is still pending from a catalog. -- FETCH : Fetch a specified CI and put it in an item library. -- 3.02-1.0 subtype CI_ID is STRING; type FETCH_TYPE is (NO_UPDATE, UPDATE, BRANCH); procedure FETCH( NAME : in CI_ID; LIBRARY : in STRING; DIRECTORY : in STRING; MODE : in FETCH_TYPE := NO_UPDATE ); -- NAME : Name of the ci to fetch -- LIBRARY : Name of the item library to put the CI in -- DIRECTORY : Name of the directory to create the itemlibrary in -- MODE : Indicates what type of update the fetch is allowing -- FETCH will put a specified CI in an item library for the user. -- If the mode is UPDATE or BRANCH the user can modify the CI and -- STORE it as a new version. If the mode is NO_UPDATE (default) -- the user is still free to modify the library, but it may NOT be -- returned to the catalog as a new version. When a CI is fetched -- for UPDATE checks are made to make sure that no one else is -- updating the same CI Documentation System User Guide Page 25 ______ CANCEL CANCEL changes the mode on the library to be no_update and deletes the user's name from the list of users updating the CIV. The default for user is the current user. Only a privileged user may cancel a FETCH done by someone else, but you may cancel any of your own fetches. If this procedure is run on a library that was not fetched for update or branch it has no effect. -- CANCEL : Cancel a FETCH that was made with the mode update -- 3.02-1.0 procedure CANCEL( LIBRARY : in STRING; USER : in STRING := "CHRIS" ); -- LIBRARY : Name of the item library the fetched CI is in -- USER : Name of the person who did the fetch -- Default is the current user -- Any user can cancel a FETCH that he or she made, but only a -- privileged user may cancel someone else's. So if the name given -- does not match the current user the catalog password will be -- asked for. Documentation System User Guide Page 26 _______________ MODIFY_PROPERTY This allows a user to update the properties on a CIV. If the properties on a CIV are wrong in some way or inconsistent a user may change them, but a user cannot delete a property that is required. -- MODIFY_PROPERTY : Modify the value associated with the given keyword -- on the specified CI -- 3.02-1.0 subtype CI_ID is STRING; procedure MODIFY_PROPERTY( NAME : in CI_ID; KEYWORD : in STRING; VALUE : in STRING ); -- NAME : Name of the CI with the property to be changed -- KEYWORD : name of the keyword to change the value of -- VALUE : New value for the keyword -- Modify_property will change the value associated with a keyword -- on a CI. The property can not be added if the keyword is -- invalid and a property can not be removed if it is required. -- To remove a property simply give it a null string for a new -- value. This change has no effect on other CIs with the same -- name. Documentation System User Guide Page 27 _______________ CHANGE_PASSWORD - CHANGE_PASSWORD will allow a privileged user to change the catalog password. The user is prompted for first the old password and then the new one. The new password is then asked for again so that it can be verified. This procedure will fail if either the old password is incorrect or the two new passwords do not match. -- CHANGE_PASSWORD : Changes the privileged user password. -- This is a privileged operation -- 3.02-1.0 procedure CHANGE_PASSWORD; -- To change the password the user must know the old password. -- The user will prompted for the old password and then the new -- password twice to verify that it was typed correctly. Documentation System User Guide Page 28 ______________ DEFINE_KEYWORD - DEFINE_KEYWORD is used to define or change the definition of keywords for the catalog. Each catalog must have its own set of keywords. A keyword can be defined with one of three different status, OPTIONAL, REQUIRED, and INVALID. If a keyword is defined as invalid it prevents libraries with that property from being added to the catalog Required keywords are keywords that must be present for a library to be added to the catalog. If any of the set of required keywords is missing the STORE or CREATE_CI will fail. Invalid keywords are still useful for looking up a CIV as a select can be done using invalid keywords. -- DEFINE_KEYWORD : Define a new keyword, or change the status of an -- existing one. -- This is a privileged operation -- 3.02-1.0 type PROPER_STATUS is (OPTIONAL, REQUIRED, INVALID); procedure DEFINE_KEYWORD( KEYWORD : in STRING; STATUS : in PROPER_STATUS := OPTIONAL ); -- KEYWORD : name of the keyword to define -- STATUS : status of the keyword -- Keywords are defined so that information about CIs can be stored -- in the database. A required keyword must always be included on -- any CI stored. Optional keywords are just that, optional. -- Invalid keywords are ones that may at one time have been valid, -- but can no longer be used to store CIs. They can still be used -- for lookup since CIs added with a keyword before it was made -- invalid are not changed. Documentation System User Guide Page 29 ______ DELETE - A CIV that is already in the catalog can be deleted using this subprogram. There are two types of DELETE, CLEAN_UP and FIX_UP, which serve different purposes. A DELETE that is being done to clean up the catalog is removing old CIs so that space can be reclaimed. A CIV that is being deleted for fix up purposes was not stored correctly in the catalog. A STORE (or CREATE_CI) can be incomplete if the user aborted in the middle or the machine crashed, so DELETE allows the incomplete CIV to be removed. The difference between the two modes is that in clean up mode the catalog manager checks there is no one with the CIV fetched, and it fails if there is someone with it fetched. Obviously, if fix up mode is fixing a STORE that was incomplete the CIV will appear to be fetched so the check is not done. -- DELETE : Delete a configuration item that is in the catalog. -- This is a privileged operation. -- 3.02-1.0 subtype CI_ID is STRING; type DELETE_TYPE is (FIX_UP, CLEAN_UP); procedure DELETE( NAME : in CI_ID; MODE : in DELETE_TYPE := CLEAN_UP ); -- NAME : Name of the configuration item to delete -- MODE : What type of delete is to be done -- There are two types of deletion that may take place. Deletion of a -- CI that is out of date and not needed, and deletion of a CI where -- the STORE only partially completed for some reason. The former is -- clean_up and the latter is fix_up. When cleaning up, the catalog -- manager checks that the CI is not currently fetched. In fix up the -- STORE was incomplete and so by definition the CI will still appear -- to be fetched. Documentation System User Guide Page 30 ___________ REMOVE_LOCK - This procedure removes a lock on the catalog. Before removing any locks like this the privileged user should be sure that the lock is not current. A lock can be left behind if the user exits the catalog by any means other than the DONE command. Read locks will prevent any other user from doing any commands involving a write lock, and a write lock will prevent any user from opening the catalog. An error message is returned if the lock does not exist. -- REMOVE_LOCK : Remove a lock that was left by a user aborting a session -- This is a privileged operation -- 3.02-1.0 type LOCK_TYPE is (READ, WRITE); type NODE_TYPE is (CATALOG_NODE, CI_NODE, INDEX_NODE); procedure REMOVE_LOCK( NAME : in STRING; LOCK : in LOCK_TYPE; NODE_NAME : in STRING := "current_catalog"; NODE : in NODE_TYPE := CATALOG_NODE ); -- NAME : Name of the person owning the lock -- LOCK : Type of lock that is to be removed -- NODE_NAME : Name of the node to be unlocked -- NODE : Type of node to be unlocked Documentation System User Guide Page 31 _________ CREATE_CI This procedure is used to create a new CI in the catalog. During creation checks will be done before any real changes are made. In this way nothing in the catalog will be changed unless there are no errors. As many errors as can be found will be reported before finishing execution enabling a user to fix up all of the known errors before proceeding. To create a CI, the library must not have been fetched for update or branch; the name must be unique and an ada identifier; it must include all required keywords, and may not include any keywords that are invalid or undefined. This is a privileged operation that should probably be controlled by a CM coordinator. -- CREATE_CI : create a new configuration item (CI) in the catalog -- 3.02-1.0 subtype CI_ID is STRING; procedure CREATE_CI( NAME : in CI_ID; LIBRARY : in STRING; HISTORY : in STRING ); -- NAME : Name of the new ci to create -- LIBRARY : Name of the item library to create the CI from -- HISTORY : Brief description of the new CI -- Any errors encountered will be reported to the user and the -- creation will not take place. In addition to having the correct -- status, the keywords on the library must be both valid, and -- include all the required ones. The history parameter will be -- stored on the new CI along with the creator and date. This -- information can be seen with the HISTORY command. Documentation System User Guide Page 32 _____ STORE STORE is similar to create, but it creates a new CIV which is based on an old one instead of an entirely new CI. It checks for slightly different errors, but like CREATE_CI as many errors as can be found will be reported and the STORE will not take place if there are any errors. To STORE a library, it must have been fetched for update or branch; the owner of the library must be the user that did the FETCH; the CIV this library is based on must exist in this catalog; the CI name must be a valid ada identifier; the properties must include all required keywords, and not include any that are invalid. This is also a privileged operation. -- STORE : Store a new version of an already existing CI -- 3.02-1.0 procedure STORE( LIBRARY : in STRING; HISTORY : in STRING ); -- LIBRARY : Name of the item library to get the CI from -- HISTORY : Description of the changes made to the new CI -- Any errors encountered will be reported to the user and the -- STORE will not take place. In addition to being fetched -- correctly, the keywords on the library must be both valid, -- and include all the required ones. The history parameter will -- be stored along with the creator and date and can be accessed -- with the history command. Documentation System User Guide Page 33 _______________ LIBRARY_MANAGER Refer to the section on Interactive Library Manager for command description and syntax. Documentation System User Guide Page 34 ____ _______ _______ ITEM LIBRARY MANAGER ___________ Description The Item Library Manager consists of a set of functions to manage a library of related files (items) called an item library. It will provide configuration control over the items and maintain multiple versions of the same item. An item library is a working copy of a configuration item (CI) and may have associated with it, properties to describe itself (See Catalog Manager for details on CI's and properties). The following commands are provided in the Item Library Manager: o LIBRARY_MANAGER o CREATE_LIBRARY o DELETE_LIBRARY o COPY_LIBRARY o LIST_LIBRARY o CREATE_ITEM o FETCH_ITEM o RETURN_ITEM o LIST_ITEM ______________ CREATE_LIBRARY -- CREATE_LIBRARY : Create an Item Library -- 3.02-1.0 subtype LIBRARY_NAME is STRING; subtype DIRECTORY_SPEC is STRING; procedure CREATE_LIBRARY( LIBRARY : in LIBRARY_NAME; DIRECTORY : in DIRECTORY_SPEC ); -- LIBRARY : Name of the item library to be created -- DIRECTORY : Name of directory to be used by this library The CREATE_LIBRARY command creates an item library with the specified name. The library name must be an Ada identifier. The directory may be any string but must be a valid directory specification for the file system in which the Item Library Manager resides. All items/information of this item library will be contained in the specified directory. The Item Library Manager does NOT provide protection for this directory except in the context of item libraries. It is recommended that no files/attributes be changed/deleted in this directory. Failure to adhere to this may cause the entire document management system to be corrupted. Documentation System User Guide Page 35 ______________ DELETE_LIBRARY -- DELETE_LIBRARY : Delete an Item Library -- 3.02-1.0 subtype LIBRARY_NAME is STRING; procedure DELETE_LIBRARY( LIBRARY : in LIBRARY_NAME ); -- LIBRARY : Name of the item library to be deleted The DELETE_LIBRARY command deletes an existing item library. Only the owner of a library may delete the library and only if the library is not pending a return into a catalog as a CI (See Catalog Manager for details of RETURN_CI function). ____________ COPY_LIBRARY -- COPY_LIBRARY : Copy an Item Library to Another Item Library -- 3.02-1.0 subtype LIBRARY_NAME is STRING; subtype DIRECTORY_SPEC is STRING; type COPY_MODE is (CURRENT, FULL); procedure COPY_LIBRARY( FROM_LIBRARY : in LIBRARY_NAME; TO_LIBRARY : in LIBRARY_NAME; TO_DIRECTORY : in DIRECTORY_SPEC; MODE : in COPY_MODE := CURRENT ); -- FROM_LIBRARY : Name of the item library to be copied -- TO_LIBRARY : Name of the new item library -- TO_DIRECTORY : Name of directory to be used by the new library -- MODE : Copy option: -- CURRENT : copy only the current version of items -- FULL : copy all versions of items The COPY_LIBRARY command copies an existing item library to another item library. The new library name must be an Ada identifier. All attributes except library ownership are copied from the existing library. A library may be copied only if there are not items within the library pending a return. The Mode option specifies if all versions of all items in the library are copied (FULL) or only the latest version of all items are copied (CURRENT). Documentation System User Guide Page 36 ____________ LIST_LIBRARY -- LIST_LIBRARY : List Libraries Owned by User -- 3.02-1.0 subtype USER_NAME is STRING; subtype LIBRARY_NAME is STRING; procedure LIST_LIBRARY( OWNER : in USER_NAME := "owner_name"; LIBRARY : in LIBRARY_NAME := "*" ); -- OWNER : Name of the library owner -- LIBRARY : Name of the library The LIST_LIBRARY command lists all libraries that satisfy the condition given by the ownership and name of the libraries. Both the library ownership and name may contain wildcard character(s) "*". ___________ CREATE_ITEM -- CREATE_ITEM : Create an Item in the Item Library -- 3.02-1.0 subtype LIBRARY_NAME is STRING; subtype FILE_NAME is STRING; procedure CREATE_ITEM( LIBRARY : in LIBRARY_NAME; FILE : in FILE_NAME; HISTORY : in STRING ); -- LIBRARY : Name of the item library -- FILE : Name of the file to be checked into the item library -- HISTORY : Description/reason for this item The CREATE_ITEM command is used to create an item in the item library from a given file. The item name will be the same as the file name and must not already exist in the item library. The History may be any character string and will be stored in the item library associated with the created item. Documentation System User Guide Page 37 __________ FETCH_ITEM -- FETCH_ITEM : Fetch an Item from an Item Library -- 3.02-1.0 subtype LIBRARY_NAME is STRING; subtype ITEM_NAME is STRING; subtype VERSION is STRING; type FETCH_MODE is (NO_UPDATE, UPDATE); procedure FETCH_ITEM( LIBRARY : in LIBRARY_NAME; ITEM : in ITEM_NAME; VERSION : in VERSION := ""; MODE : in FETCH_MODE := NO_UPDATE ); -- LIBRARY : Name of the item library -- ITEM : Name of the item to be fetched from the item library -- VERSION : Version specification -- MODE : Fetch mode: -- NO_UPDATE : check out an item for read only -- UPDATE : check out an item for update The FETCH_ITEM command is used to check an item out of the item library. The checked out item will be a file in the current directory with the item name as its file name. The Mode specifies whether the item is to be checked out as read only (NO_UPDATE) or for updating and eventual return to the item library (UPDATE). Only the current version may be checked out for UPDATE provided that it is not already checked out for UPDATE. The version specification may be any numeric in string format (eg. "3") or a null string for the current version. ___________ RETURN_ITEM -- RETURN_ITEM : Return a File to an Item Library -- 3.02-1.0 subtype LIBRARY_NAME is STRING; subtype FILE_NAME is STRING; procedure RETURN_ITEM( LIBRARY : in LIBRARY_NAME; FILE : in FILE_NAME; HISTORY : in STRING ); -- LIBRARY : Name of the item library -- FILE : Name of the file to be returned to the item library Documentation System User Guide Page 38 -- HISTORY : Description/reason for the change(s) in this item The RETURN_ITEM command is used to check a file back into the item library as a new version of an item previously checked out (see FETCH_ITEM). The History may be any character string and will be stored in the item library associated with this new version of an item. _________ LIST_ITEM -- LIST_ITEM : List Item(s) in the Item Library -- 3.02-1.0 subtype LIBRARY_NAME is STRING; subtype ITEM_NAME is STRING; subtype VERSION is STRING; type LIST_MODE is (LONG, SHORT); procedure LIST_ITEM( LIBRARY : in LIBRARY_NAME; ITEM : in ITEM_NAME := "*"; VERSION : in VERSION := ""; MODE : in LIST_MODE := SHORT ); -- LIBRARY : Name of the item library -- ITEM : Name of the item to list -- VERSION : Version specification -- MODE : List mode: -- SHORT : list item/version name(s) only -- LONG : list attributes as well as item/version name(s) The LIST_ITEM command lists item(s) in the item library that satisfies the condition specified by Item and Version. Both Item and Version may contain wildcard character(s) "*". The Mode specifies whether the list is to contain only the item name and version (SHORT) or item name, version, and associated attributes (LONG). _______________ _ ___________ _______ _______ LIBRARY_MANAGER : Interactive Library Manager -- LIBRARY_MANAGER : Interactive Library Manager Tool -- 3.02-1.0 subtype LIBRARY_NAME is STRING; procedure LIBRARY_MANAGER( Documentation System User Guide Page 39 LIBRARY : in LIBRARY_NAME := ""; PROMPT : in STRING := "" ); -- LIBRARY : Name of the item library -- PROMPT : Prompt string This command invokes the interactive library management tool. The item library name if given must be an Ada identifier. The PROMPT may be any string and will appear as a prompt for the interactive library manager. The following interactive commands are provided: o CREATE_LIBRARY o DELETE_LIBRARY o COPY_LIBRARY o LIST_LIBRARY o CREATE_ITEM o FETCH_ITEM o RETURN_ITEM o CANCEL_ITEM o LIST_ITEM o DELETE_ITEM o PURGE_ITEM o RENAME_ITEM o RENAME_VERSION o SHOW_HISTORY o ADD_PROPERTY o DELETE_PROPERTY o MODIFY_PROPERTY o LIST_PROPERTY o ENTER_LIBRARY o HELP o EXIT The HELP command shows brief descriptions of all Interactive Library Manager commands. The EXIT command is used to terminate the Interactive Library Manager session. The following commands have the same function and command syntax as described immediately above: CREATE_LIBRARY DELETE_LIBRARY COPY_LIBRARY LIST_LIBRARY The following commands have the same function as described immediately above but the command syntax differs in that no library specifications are given: CREATE_ITEM Documentation System User Guide Page 40 FETCH_ITEM RETURN_ITEM LIST_ITEM ___________ CANCEL_ITEM - -- CANCEL_ITEM : Cancel a Pending Return for an Item in the Item Library -- 3.02-1.0 subtype ITEM_NAME is STRING; procedure CANCEL_ITEM( ITEM : in ITEM_NAME ); -- ITEM : Name of the item to cancel the pending return The CANCEL_ITEM command cancels a return pending state of an item in the item library without returning the file back into the item library. The item must be checked out for update to be canceled. ___________ DELETE_ITEM - -- DELETE_ITEM : Delete Item(s) in an Item Library -- 3.02-1.0 subtype ITEM_NAME is STRING; subtype VERSION is STRING; procedure DELETE_ITEM( ITEM : in ITEM_NAME; VERSION : in VERSION := "" ); -- ITEM : Name of the item(s) to be deleted in the item library -- VERSION : Version specification The DELETE_ITEM command deletes item(s) from the item library. Both Item and Version specification may contain wildcard character(s) "*". All items/versions that satisfy the specifications and whose ownership requirements are satisfied are deleted from the item library. Documentation System User Guide Page 41 __________ PURGE_ITEM - -- PURGE_ITEM : Purge Item(s) in an Item Library -- 3.02-1.0 subtype ITEM_NAME is STRING; procedure PURGE_ITEM( ITEM : in ITEM_NAME ); -- ITEM : Name of the item(s) to be purged in the item library The PURGE_ITEM command deletes all but the current version(s) of item(s) from the item library. Item specification may contain wildcard character(s) "*". All items that satisfy the specification and whose ownership requirements are satisfied will have all but their highest version(s) deleted. ___________ RENAME_ITEM - -- RENAME_ITEM : Rename Item in an Item Library -- 3.02-1.0 subtype ITEM_NAME is STRING; procedure RENAME_ITEM( FROM_ITEM : in ITEM_NAME; TO_ITEM : in ITEM_NAME ); -- FROM_ITEM : Name of the item to be renamed in the item library -- TO_ITEM : New item name The RENAME_ITEM command renames an item in the item library. The item name specification may not contain wildcard character "*". The validity of the new item name is not checked by RENAME_ITEM. Invalid item name (ie. name that may not conform to the file name specification of the file system on which the library manager resides) will make the item unretrievable by FETCH_ITEM operation which will attempt to create an external file with the same name as the item name being fetched. Documentation System User Guide Page 42 ______________ RENAME_VERSION - -- RENAME_VERSION : Rename Version of Item(s) in an Item Library -- 3.02-1.0 subtype ITEM_NAME is STRING; subtype VERSION is STRING; procedure RENAME_VERSION( ITEM : in ITEM_NAME; FROM_VERSION : in VERSION; TO_VERSION : in VERSION ); -- ITEM : Name of the item(s) to be renamed in the item library -- FROM_VERSION : Version of item(s) to be renamed -- TO_VERSION : New version of item(s) The RENAME_VERSION command renames a version of item(s) in the item library. The version specification may not contain wildcard character "*". The current version may be specified as a null string "". The item specification may contain wildcard characters "*". Inappropriate usage of this command may cause regression in the item versions. ____________ SHOW_HISTORY - -- SHOW_HISTORY : Show History of Item(s) in an Item Library -- 3.02-1.0 subtype ITEM_NAME is STRING; subtype VERSION is STRING; procedure SHOW_HISTORY( ITEM : in ITEM_NAME := "*"; VERSION : in VERSION := "" ); -- ITEM : Name of the item to list -- VERSION : Version specification The SHOW_HISTORY command lists all history descriptions associated with all version(s) of item(s) that satisfy the condition specified by Item and Version. Both Item and Version may contain wildcard character(s) "*". The current version is specified by a null string "". Documentation System User Guide Page 43 ____________ ADD_PROPERTY - -- ADD_PROPERTY : Add a Property Keyword/Value to the Item Library -- 3.02-1.0 procedure ADD_PROPERTY( KEYWORD : in STRING; VALUE : in STRING ); -- KEYWORD : Property keyword -- VALUE : Property value The ADD_PROPERTY command is used to associate a new keyword/value property description to an item library. The property keyword to be added must not exist. Both the keyword and the value must be an Ada identifier. _______________ DELETE_PROPERTY - -- DELETE_PROPERTY : Delete a Property Keyword from the Item Library -- 3.02-1.0 procedure DELETE_PROPERTY( KEYWORD : in STRING ); -- KEYWORD : Property keyword The DELETE_PROPERTY command is used to delete a property description associated with an item library. The property keyword to be delete must exist. The keyword must be an Ada identifier. _______________ MODIFY_PROPERTY - -- MODIFY_PROPERTY : Change a Property Keyword/Value in the Item Library -- 3.02-1.0 procedure MODIFY_PROPERTY( KEYWORD : in STRING; VALUE : in STRING ); -- KEYWORD : Property keyword -- VALUE : Property value Documentation System User Guide Page 44 The MODIFY_PROPERTY command is used to change the value of a property description keyword associated with an item library. The property keyword whose value is to be changed must exist. Both the keyword and the value must be an Ada identifier. _____________ LIST_PROPERTY - -- LIST_PROPERTY : List Property Keyword/Value in the Item Library -- 3.02-1.0 procedure LIST_PROPERTY( KEYWORD : in STRING := "*" ); -- KEYWORD : Property keyword The LIST_PROPERTY command lists keyword/value property description(s) associate with an item library. The keyword may contain wildcard character(s) "*" but otherwise must be an Ada identifier. _____________ ENTER_LIBRARY - -- ENTER_LIBRARRY : Enter a Given Item Library -- 3.02-1.0 subtype LIBRARY_NAME is STRING; procedure ENTER_LIBRARY( LIBRARY : in LIBRARY_NAME ); -- LIBRARY : Name of the item library The ENTER_LIBRARY command sets the given library as a current item library. All subsequent commands will operate on the given library. A null library name resets the current library to the library for which the Interactive Library Manager was invoked. Documentation System User Guide Page 45 ________ Examples The following sequence of commands describe a typical item library operations for creating and manipulating an item library. Assume that there are three (3) files called FILE1.ADA, FILE2.SPC, and FILE2.BDY and one wishes to create an item library PROJECT_LIBRARY. CREATE_LIBRARY ("PROJECT_LIBRARY", "[.PLIB]"); -- create a library PROJECT_LIBRARY in a directory -- PLIB relative to the current directory (VAX/VMS notation) LIBRARY_MANAGER ("PROJECT_LIBRARY", "=>"); -- enter the interactive library manager for PROJECT_LIBRARY -- prompt string is => => ADD_PROPERTY ("PROGRAMMER", "JOHN"); => ADD_PROPERTY ("LANGUAGE", "ADA"); => ADD_PROPERTY ("PROJECT", "XXX_123"); -- give the library properties with appropriate values => CREATE_ITEM ("FILE1.ADA", "Description of FILE1"); => CREATE_ITEM ("FILE2.SPC", "Description of FILE2 Spec"); => CREATE_ITEM ("FILE1.ADA", "Description of FILE2 Body"); -- create items in the library with descriptions -- associated with each item EXIT; -- exit the interactive library manager -- -- now there is a need to change FILE2.BDY -- FETCH_ITEM ("PROJECT_LIBRARY", "FILE2.BDY", UPDATE); -- check FILE2.BDY out of the library for update -- change FILE2.BDY using any editor RETURN_ITEM ("PROJECT_LIBRARY", "FILE2.BDY", "Change description"); -- check FILE2.BDY back into the library -- now there will be two versions of FILE2.BDY in the library ____ Bugs External interrupt(s) during item library management operations may cause abnormal behavior. Documentation System User Guide Page 46 ________ __________ ______ ____ _________ DOCUMENT MANAGEMENT SYSTEM FILE GENERATOR ____________ INTRODUCTION FILEGEN provides the documentation management system (DocMgr) with the capability to combine one or more files to create a single output file. The "source file" may contain directives which are processed by FILEGEN to generate the output file. These directives begin with the character "#" (sharp sign) in column one. The INCLUDE directive may be used to merge additional files into the output file. Other directives allow the file name (or the configuration identifier if the file is a component of a configuration item), the version number and the file modification date to be inserted into the output file. This provides a mechanism through which any file that is under configuration control can be uniquely identified when it is checked out of the configuration management system. _______ ______ Command Format -- FileGen : Generate a target file from a source file -- 3.02-1.0 FileGen( Source : string; Output : string := ""; Catalog : string := ""; CI_Name : CI_ID_Type := "" ); Source: -- File name or name of a component of CI Output: -- Name of the output file (default is standard output) Catalog: -- Name of a CI Catalog (default is none) CI_Name: -- Name of a CI (default is none) __________ Parameters The OUTPUT parameter specifies the name of the file which is to contain the file to be generated. It is a host system file specification. The input file to be processed is specified by some combination of the remaining three parameters, depending on whether the input file is an ordinary text file, or a component within a configuration item. If the input file is an "ordinary file" (that is, one that has not been stored as as a component of a configuration item), then the SOURCE parameter is an ordinary file specification (on VMS, "USERMAN.SRC" or "[WORK.DOC]USERMAN.SRC", etc.), and CI_NAME is a null string. The CATALOG parameter is necessary only if an INCLUDE directive that specifies a CI component is encountered in one of the files being processed. If the source file is currently stored in an item library, then it cannot be processed by fileGen directly. Instead, it must be checked out of the library and processed as an ordinary file. Documentation System User Guide Page 47 Finally, if the source file is currently stored as a configuration item, then CATALOG is the name of the configuration item catalog, CI_NAME is the name of the configuration item, and SOURCE is the name of the file within this configuration item. The SOURCE parameter has the form of an ordinary host system file name. If the item is inside of an item library or a configuration item, it must be a simple file name (no directory path). The CATALOG parameter must be a valid Ada identifier. The CI_Name parameter is a valid Ada identifier followed by one or more spaces followed by a version number. See the section on the Catalog Manager for details on the version numbering scheme. ___________ Description FILEGEN has three basic functions: 1. Extracting files from an Item Library or from a configuration item. 2. File inclusion 3. Substitutions: - Version ID - Date of last modification - CI_ID - ITEM_ID The following are the directives that may be used in a file processed by FILEGEN. Lines that do not begin with a sharp sign (#) are simply copied to the output file. If the sharp sign appears twice in a row (in columns one and two), then the line is copied to the output file starting with column two (the first sharp sign is deleted). This makes it relatively easy to generate output files containing a sharp sign in column one, should the need arise. There are three kinds of directives: includes, substitutions, and definitions. The Include directive causes the contents of the designated file to be recursively processed by FILEGEN and copied to the output file. Substitution directives are evaluated and replaced by their values before the line is copied to the output file. Definitions assign string values to variables and do not generate any output. scope of a variable is limited to the file which defines it. In a directive, everything following a double dash is a comment (as in Ada) and is ignored. If a directive results in a line that is entirely blank, the line is not copied to the output file. Thus lines of the form #-- <text> are filtered from the input file. Documentation System User Guide Page 48 The syntax of the directives is as follows: Directive = "Set" Variable ":=" StrVal -- Variable definition | "Include" "file" StrVal -- File inclusion | "Include" "il_item" StrVal, StrVal, VSpec -- File from item library | "Include" "ci_comp" StrVal, StrVal, VSpec -- File from CI Catalog | Expr -- Substitution StrVal = String | Variable VSpec = DottedNumber Expr = Primary -- Simple substitution | Primary Expr -- Concatenation Primary = StrVal -- String literal or variable | "Date" -- Replace with date of last modification | "CI" -- Replaced by CI name of this file | "ITEM" -- Replaced by Item name of this file | "Version" -- Replaced by Version Number of this file Variable = (an Ada identifier) ________ ___________ Variable Definitions A variable definition assigns a string value to an identifier. Subsequent uses of the variable are replaced by its value. If a variable is redefined, a warning message is issued. The scope of a variable is limited to the file that contains its definition. Variables must be defined before use. If a number of files are to be extracted from the same configuration item, it may be convenient to assign the configuration item name and version number to variable as in the following example: #set CI := "System_Documentation" #set VNum := 5.3 #include CI_COMP CI, "Part_1", VNum #include CI_COMP CI, "Part_2", VNum #include CI_COMP CI, "Part_3", VNum Then, it is a simple matter to change the definition of CI or VNum to extract the same files from a different configuration item or different version of the same item. ___ _______ _________ The INCLUDE Directive There are three forms of the include directive. In all cases, the directive is replaced by the contents of the file that it specifies. The file can be either an ordinary host file, an item within an item library, or a file from a configuration item. To include an ordinary host system file, the following form of the INCLUDE directive is used: Documentation System User Guide Page 49 #INCLUDE FILE <host system file name> To include an item from within an item library, the name of the library, the name of the item, and the desired revision number must all be specified: #INCLUDE IL_ITEM <library name> <item name> <version number> The library name must be a valid Ada identifier. The item name is a host system file name, and the version number is a single digit number. Finally, to include an item from within a configuration item catalog, the name of the configuration item, the name of the file within that CI, and the desired revision number must all be specified: #INCLUDE CI_COMP <CI name> <file name> <version number> the CI name must be a valid Ada identifier. The file name is a simple host system file name, and the version number may contain several components to reflect branching within the configuration item catalog (eg. 1 or 1.1.3 or 1.2.3, etc.) _____________ Substitutions If a directive consists of a sequence of expressions, the value of each expression is simply copied to the output file and then the output line is terminated. ________ Examples Assuming the following command is given to invoke FILEGEN FILEGEN("USERMAN.FGN", "USERMAN.RNO"); In this case, the file USERMAN.fgn will be processed to generate a file called USERMAN.RNO. No catalog or item library will be used. The following examples show how each directive might be used. 1. Inserting the date of last modification into the output file: IN: #"This file last modified " Date OUT: This file last modified " 15-Jan-1985 15:33.32 2. Include a specified file: IN: #Include file "[DOC.WORK]INTRO.FGN" OUT: (Contents of the specified file [DOC.WORK]INTRO.FGN) 3. Variable definition IN: #SET Dir := "[WORK.DOC]" #"-- The value of DIR is: " Dir Documentation System User Guide Page 50 OUT: -- The value of DIR is: [WORK.DOC] 4. Substitutions of CI, Item, and Version IN: #"This is " Item " of " CI ", version " Version "." OUT: This is Item? of CI?, version Version? The above example shows that if the Item, CI, or Version substitutions are requested when an ordinary file is being processed, the strings "Item?", "CI?", and "Version?" are used. This allows a FILEGEN source file to be checked out before it becomes a component of a configuration item. Assuming the following command is given to invoke FILEGEN: FILEGEN("TEST.ADAGEN", "TEST.ADA", "My_Catalog", "TestCI 3"); The following show some directives and the associated output 1. Inserting the CI_ID as a comment in the output file: IN: #"-- Version " Version " of " CI "." Item OUT: -- Version 3 of My_Catalog.TestCI 2. Inserting the CI_ID and date of last modification as a literal string in the output file: IN: #"Version_ID: constant string :=" #""" CI "." Item "(" Version ") of " Date """;" OUT: Version_ID: constant string := "My_Catalog.TestCI(3) of 8/12/85"; 3. Include a specified file: IN: #Include file "decls.ada" OUT: (Contents of the specified file) 4. Include a specified item (file) called "other.dat" from the same configuration item as is being processed: IN: #Include CI_COMP CI, "other.dat", Version OUT: (Contents of neighboring item OTHER.DAT) 5. Include a specified item from a different Item Library: IN: #Include IL_ITEM "Joes_IL", "other.dat", "3" OUT: (Contents of item OTHER.DAT version 3 from JOES_IL) Documentation System User Guide Page 51 6. Include a specified item from some other CI: IN: #Include CI_COMP Joes_CI, other.dat, 3.2.7 OUT: (Contents of item OTHER.DAT from JOES_CI version 3.2.7) 7. Include two items from the same CI: IN: #Current_Version := "3.2.8" #Include CI_COMP Joes_CI, FIRST.DAT, Current_Version #Include CI_COMP Joes_CI, SECOND.DAT, Current_Version OUT: (Contents of item FIRST.DAT from JOES_CI version 3.2.8) (Contents of item SECOND.DAT from JOES_CI version 3.2.8) _____ Notes There is no way to specify the "latest version" of an item in a CI. This is because 1) doing so would violate the requirement that it be possible to recreate any CI at any time and 2) since branches are allowed, the "latest version" is not well defined. Documentation System User Guide Page 52 ________ _______ DOCUMENT PRINTER ___________ Description The Document Printer produces a page separated output file from any number of input files. The page header and footer lines may be specified as well as the output page size, margin setting, and line numbering. ________ _______ _______ ______ Document Printer Command Format -- PAGINATE : Formats file(s) as specified -- 3.02-1.00 subtype FILE_NAME is STRING; type SOURCE_LIST is array (POSITIVE range <>) of FILE_NAME; subtype PAGE_TYPE is INTEGER range 1 .. 999; subtype MARGIN_TYPE is INTEGER range 0 .. 20; type SWITCH is (ON, OFF); procedure PAGINATE( SOURCE_LIST : in SOURCE_LIST; OUTPUT : in FILE_NAME; HEADER : in STRING := "~F(L50) ~D ~T Page ~P(R3)"; FOOTER : in STRING := ""; PAGE : in PAGE_TYPE := 60; MARGIN : in MARGIN_TYPE := 0; NUMBER : in SWITCH := OFF ); -- SOURCE_LIST : List of file name(s) to be formatted -- OUTPUT : Output file name (defaults to standard output) -- HEADER : Header text -- FOOTER : Footer text -- PAGE : Number of lines per page (excluding header/footer) -- MARGIN : Left margin size -- NUMBER : Line numbering The header/footer text may contain substitution sequence(s) as place holder(s) for actual data to be inserted in the output file. The substitution sequence is defined by an escape character tilde (~) followed by a substitution character and may be followed by an optional alignment specification consisting of an alignment character and a numeric field size. The general format of the substitution sequence is ~S(Ann) where S is the substitution character and A is the alignment character followed by a number nn. Documentation System User Guide Page 53 The valid substitution characters are: F : output external file name P : current page number D : current date (eg. 03/15/86) C : current calendar date (eg. March 15, 1986) T : current time (eg. 04:53:32) The valid optional alignment character A are: L : left align the text R : right align the text C : center the text The nn following the alignment character specifies the number of spaces the text will displace in the header/footer text. The case is not significant after the escape character tilde (~). If the escape character is followed by any character other than a valid substitution character the tilde will not be printed and no substitution is performed. To print a tilde character in the output header/footer two (2) consecutive tilde characters must be written in the header/footer specification. Documentation System User Guide Page 54 ________ Examples The following example takes three (3) files FILE1..DAT, FILE2..DAT, and FILE3..DAT as input (SOURCE_LIST) and creates a paginated output file FILES..OUT (OUTPUT). The header (HEADER) consists of the output file name left aligned to 60 characters followed by the date and time. The footer (FOOTER) consists of the page number centered in the middle of the page. The whole text is offset (MARGIN) by five (5) characters at the left margin. PAGINATE ( SOURCE_LIST => ("FILE1.DAT", "FILE2.DAT", "FILE3.DAT"), OUTPUT => "FILES.OUT", HEADER => "~F(L60) ~D ~T", FOOTER => "~P(C80)", MARGIN => 5); Documentation System User Guide Page 55 ____ Bugs There are no known bugs. Documentation System User Guide Page 56 ____________ INSTALLATION Refer to the Byron installation guide. Documentation System User Guide Page 57 ________ _ APPENDIX 1 To rebuild the DOCMGR tools: 1. Compile all of the abstractions into an Ada program library 2. Compile the files in the [.DOCMGR.SOURCE] directory into the same library or into a sublibrary of that library. The file DOCMGR.CO lists all of the DOCMGR source files in a valid compilation order. 3. Link the following executables: Executable Name Ada program unit name ADDUSER.EXE Add_User CHCONSIST.EXE Check_Consistency COPYL.EXE Copy_Library CREATECAT.EXE Create_Catalog CREATEI.EXE Create_Item CREATEL.EXE Create_Library CREATERM.EXE Cre_RM DELHUSER.EXE Delete_HIF_User DELETEL.EXE Delete_Library DELUSER.EXE Delete_User FETCHI.EXE Fetch_Item FILEGEN.EXE FileGen LIBMGR.EXE Interactive_Library_Manager LISTCAT.EXE List_Catalogs LISTL.EXE List_Library LISTI.EXE List_Item OPENCAT.EXE Open_Catalog PAGINATE.EXE Paginate RETURNI.EXE Return_Item This release is built on a version of the HIF (Host Interface Facility) called the Super-HIF that has known problems. The current version of the Super-HIF will not allow multiple processes to access item(s) in the Super-HIF at the same time. The consequence of this is that only one process may access the catalog or th library at a given time. :::::::::::::: docmgr.rno :::::::::::::: .RM 67 .PS ,67 .STHL ,,2,0,,1,0,,! turns off section numbering, second level and lower not all caps .EUN ! enable underlining .FLAGS ACCEPT % ! Make underscore a printable character, we don't need overstrike .T Documentation System User Guide .C Documentation System User Guide .SK .HL ^&Introduction\& .SK .P The Documentation System is made up of four parts: the catalog manager; the item library manager; paginate and filegen. The catalog manager is the interface to configuration item catalogs, and the item library manager is the interface to item libraries. These interfaces will be described in detail in later sections, although some commands will be mentioned here to provide an overview of the system. Filegen and paginate are utilities to be used with the Documentation System. .HL ^&Becoming a Documentation System User\& .SK .P In order to use the Documentation System the user must be a HIF user. There is an operation ADD_USER that will make a user a HIF user. ADD_USER has two parameters: a directory where HIF data files will be kept and a user id. The user id defaults to the current user id. If you are adding yourself there is no need to specify the second parameter. In order to be recognized as a HIF user your HIF user id must be the same as your login id. In addition to ADD_USER there is DELETE_USER that takes no parameters and removes the current user from the HIF. .P The user must also set two logical variables called HIF_DIRECTORY and HIF_FDL. This is best done at login time. The values for both of these variables are determined at installation time by the person that sets up the documentation system. All operations will fail if the user is not a HIF user. .HL ^&Overview of the Catalog Manager and Item Library Manager\& .SK .P A configuration item (CI) is a collection of files that are logically connected. For example the set of files that make up a list package could be grouped as one CI. The user has the option of including all files, source and documentation, in one CI or dividing the files into one or more CIs as seems appropriate. The degenerate case would be where a CI contains only one item. .P The way in which the files are grouped prior to making them a CI is to put them into an item library. An item is not a file. It is the 'contents' of that file. In this way an item library can contain any number of versions of one 'item'. Item libraries are created with the item library manager command CREATE_LIBRARY. A library is created empty and your files are put into the library with the command CREATE_ITEM. More versions of an item are created by calling FETCH_ITEM, modifying the file and then calling RETURN_ITEM. .P In order to make a CI there must be a catalog in which to put it. Catalogs are created with the CREATE_CATALOG command. Any number of catalogs can be in the same documentation system, but they must have unique names. Different projects may want to keep their CIs in different catalogs. There are three other commands that act on catalogs: LIST_CATALOGS, CHECK_CONSISTENCY and OPEN_CATALOG. LIST_CATALOGS will list all catalogs in the documentation system; CHECK_CONSISTENCY walks a catalog structure reporting any inconsistencies; OPEN_CATALOG is an interactive tool that provides the user interface to CIs in a catalog. Any commands following that deal with CIs are actually commands within the OPEN_CATALOG tool. .P To make a CI you must have an item library. A CI is made from the library when you execute the command CREATE_CI. At this time the contents of the library are put into the catalog under the name that you give it and the library is deleted. For example, suppose the list package files were put into a library, now they are in a controlled environment for the developer to modify and test the code until a working list package is arrived at. The user should then let a configuration management (CM) coordinator know which library to take. Using CREATE_CI the CM coordinator will make a CI from the specified library. CREATE_CI takes the most recent version of each item, and other information stored in the library moves it into the catalog under the name given to CREATE_CI which might have been 'list' for the list package. A CI version of '1' will be assigned to this CI and so the CI id of this CI version is 'list 1'. .P Although there are versions of a CI, each version could be viewed as a configuration item itself. This is easy to understand since each 'version' exists for some reason, and even though new development would probably use the most current version of any CI it needs, there will undoubtedly be something that still depends on an older version, So to avoid confusion, from now on 'CI' will refer to the complete collection of versions that share the same CI name, and 'CI version' (CIV) will refer to a particular instance of a CI. A CI id identifies a particular CI version. .P When a CIV is put into the catalog other information in addition to the files is kept. Properties are part of the information taken from the library. A property is a keyword, value pair that identifies some attribute of the CIV. For example the list package might have a property: LANGUAGE-ADA. Properties are attached to a CIV when it is in the item library stage. There are item library commands to add, delete and change properties. The properties are not checked, however, until the user tries to make the library a CIV. The reason for this is that different catalogs can have different sets of valid keywords and when you just have an item library there is nothing to determine which catalog in which it may be put later. .P The valid keywords for a catalog are defined by a privileged user, usually the person that created the catalog, and keywords can be defined to be required on every CIV. When the CIV is created or stored in the catalog its properties are checked to make sure they all have valid keywords and all the required ones are included. Then the properties are stored in a database that allows users to query the catalog by properties. .P Having determined through the database what CIV they want a user can FETCH it to modify or just to use. When a CIV is fetched its contents are put into a specified item library. At this point the user may fetch and return items as before, and the item library in this case can be thought of as a working copy of the CI. .P When the library is again ready to become a CIV it is returned to the catalog with the STORE operation. The store operation will give the CIV a CI id that has the same CI name as before and the next number sequentially for the version. For example, suppose a user wanted to add a labeled list to the list package. The CIV could be fetched, modified and then stored. It would have a CI id of 'list 2'. .P This development cycle can be repeated any number of times. The user should note that CREATE_CI and STORE are privileged commands that can only be executed by a person that knows the catalog password. This would normally be the person that created the catalog or a CM coordinator. On the other hand any user may do a FETCH and most of the other commands in the interactive tool. .HL ^&Paginate and FILEGEN\& .SK .P Paginate and Filegen are utilities that can be used with the catalog manager and the item library manager, or independently. Paginate will produce an output file with page breaks , a header and a footer from any text input file. The options it allows are described fully in the paginate section. .P Filegen is a file inclusion utility. Given a file containing filegen directives it will produce an output file that contains the original file's text, the text of any files included and other information like the current date and the CI name of the CIV the file is in. The information that can be included is described in detail in the filegen section dealing with the filegen directives. .P In addition to being able to include other files from your file system, you can include files from a library or even a CIV in a catalog. You can also produce output from a file inside a CIV. If you give as input the name of an item in a CIV, the the CIV's CI id and the catalog name, file gen will produce an output file that is the text of the input item, and the information generated by the filegen directives. .REQ "catmgr.rno" .REQ "libmgr.rno" .REQ "fgen.rno" .REQ "paginate.rno" .PAGE .HEADER LEVEL 1^&Installation\& .PARAGRAPH Refer to the Byron installation guide. .PAGE .RM 80 .PS ,80 .HEADER LEVEL 1^&Appendix 1\& .BLANK .NO FILL .NO JUSTIFY .REQ "[-]read.me" .FILL .JUSTIFY .RM 67 .PS ,67 :::::::::::::: docmgrc.mem :::::::::::::: CONTENTS 1 INTRODUCTION . . . . . . . . . . . . . . . . . . . . 1 2 BECOMING A DOCUMENTATION SYSTEM USER . . . . . . . . 1 3 OVERVIEW OF THE CATALOG MANAGER AND ITEM LIBRARY MANAGER . . . . . . . . . . . . . . . . . . . . . . 1 4 PAGINATE AND FILEGEN . . . . . . . . . . . . . . . . 3 5 CATALOG MANAGER . . . . . . . . . . . . . . . . . . 4 5.1 Description . . . . . . . . . . . . . . . . . . . 4 5.2 Configuration Item Versions . . . . . . . . . . . 4 5.3 Configuration Identification . . . . . . . . . . . 5 5.4 Using The Catalog Manager . . . . . . . . . . . . 5 5.5 Example Session . . . . . . . . . . . . . . . . . 5 5.6 CATALOG MANAGER COMMANDS . . . . . . . . . . . . . 7 5.6.1 CREATE_CATALOG . . . . . . . . . . . . . . . . . 7 5.6.2 OPEN_CATALOG . . . . . . . . . . . . . . . . . . 8 5.6.3 LIST_CATALOGS . . . . . . . . . . . . . . . . . 9 5.6.4 CHECK_CONSISTENCY . . . . . . . . . . . . . . 10 5.7 Guide To The Interactive Catalog Manager . . . . 12 5.8 Using The Interactive Catalog Manager . . . . . 12 5.8.1 Catalog Functions . . . . . . . . . . . . . . 12 5.8.2 Query Functions . . . . . . . . . . . . . . . 12 5.8.2.1 Catalog Queries . . . . . . . . . . . . . . 12 5.8.2.2 Configuration Item Queries . . . . . . . . . 12 5.8.3 Configuration Item Commands . . . . . . . . . 13 5.8.4 Priviledged Operations . . . . . . . . . . . 13 5.8.5 Item Library Operations . . . . . . . . . . . 13 5.9 INTERACTIVE COMMANDS . . . . . . . . . . . . . . 14 5.9.1 HELP . . . . . . . . . . . . . . . . . . . . 14 5.9.2 SELECT_CIS . . . . . . . . . . . . . . . . . 15 5.9.2.1 Selection Syntax: . . . . . . . . . . . . . 15 5.9.3 CLEAR_SELECTED_SET . . . . . . . . . . . . . 16 5.9.4 PRINT_SET . . . . . . . . . . . . . . . . . . 17 5.9.5 LIST_CIS . . . . . . . . . . . . . . . . . . 18 5.9.6 LIST_KEYWORDS . . . . . . . . . . . . . . . . 19 5.9.7 LIST_VERSIONS . . . . . . . . . . . . . . . . 20 5.9.8 DESCRIBE . . . . . . . . . . . . . . . . . . 21 5.9.9 HISTORY . . . . . . . . . . . . . . . . . . . 22 5.9.10 LIST_COMPONENTS . . . . . . . . . . . . . . . 23 5.9.11 FETCH . . . . . . . . . . . . . . . . . . . . 24 5.9.12 CANCEL . . . . . . . . . . . . . . . . . . . 25 5.9.13 MODIFY_PROPERTY . . . . . . . . . . . . . . . 26 5.9.14 CHANGE_PASSWORD . . . . . . . . . . . . . . . 27 5.9.15 DEFINE_KEYWORD . . . . . . . . . . . . . . . . 28 5.9.16 DELETE . . . . . . . . . . . . . . . . . . . . 29 5.9.17 REMOVE_LOCK . . . . . . . . . . . . . . . . . 30 5.9.18 CREATE_CI . . . . . . . . . . . . . . . . . . 31 5.9.19 STORE . . . . . . . . . . . . . . . . . . . . 32 5.9.20 LIBRARY_MANAGER . . . . . . . . . . . . . . . 33 6 ITEM LIBRARY MANAGER . . . . . . . . . . . . . . . 34 6.1 Description . . . . . . . . . . . . . . . . . . 34 6.2 CREATE_LIBRARY . . . . . . . . . . . . . . . . . 34 6.3 DELETE_LIBRARY . . . . . . . . . . . . . . . . . 35 6.4 COPY_LIBRARY . . . . . . . . . . . . . . . . . . 35 6.5 LIST_LIBRARY . . . . . . . . . . . . . . . . . . 36 Page 2 6.6 CREATE_ITEM . . . . . . . . . . . . . . . . . . 36 6.7 FETCH_ITEM . . . . . . . . . . . . . . . . . . . 37 6.8 RETURN_ITEM . . . . . . . . . . . . . . . . . . 37 6.9 LIST_ITEM . . . . . . . . . . . . . . . . . . . 38 6.10 LIBRARY_MANAGER : Interactive Library Manager . 38 6.10.1 CANCEL_ITEM . . . . . . . . . . . . . . . . . 40 6.10.2 DELETE_ITEM . . . . . . . . . . . . . . . . . 40 6.10.3 PURGE_ITEM . . . . . . . . . . . . . . . . . . 41 6.10.4 RENAME_ITEM . . . . . . . . . . . . . . . . . 41 6.10.5 RENAME_VERSION . . . . . . . . . . . . . . . . 42 6.10.6 SHOW_HISTORY . . . . . . . . . . . . . . . . . 42 6.10.7 ADD_PROPERTY . . . . . . . . . . . . . . . . . 43 6.10.8 DELETE_PROPERTY . . . . . . . . . . . . . . . 43 6.10.9 MODIFY_PROPERTY . . . . . . . . . . . . . . . 43 6.10.10 LIST_PROPERTY . . . . . . . . . . . . . . . . 44 6.10.11 ENTER_LIBRARY . . . . . . . . . . . . . . . . 44 6.11 Examples . . . . . . . . . . . . . . . . . . . . 45 6.12 Bugs . . . . . . . . . . . . . . . . . . . . . . 45 7 DOCUMENT MANAGEMENT SYSTEM FILE GENERATOR . . . . 46 8 INTRODUCTION . . . . . . . . . . . . . . . . . . . 46 8.1 Command Format . . . . . . . . . . . . . . . . . 46 8.2 Parameters . . . . . . . . . . . . . . . . . . . 46 8.3 Description . . . . . . . . . . . . . . . . . . 47 8.4 Variable Definitions . . . . . . . . . . . . . . 48 8.5 The INCLUDE Directive . . . . . . . . . . . . . 48 8.6 Substitutions . . . . . . . . . . . . . . . . . 49 8.7 Examples . . . . . . . . . . . . . . . . . . . . 49 8.8 Notes . . . . . . . . . . . . . . . . . . . . . 51 9 DOCUMENT PRINTER . . . . . . . . . . . . . . . . . 52 9.1 Description . . . . . . . . . . . . . . . . . . 52 9.2 Document Printer Command Format . . . . . . . . 52 9.3 Examples . . . . . . . . . . . . . . . . . . . . 54 9.4 Bugs . . . . . . . . . . . . . . . . . . . . . . 55 10 INSTALLATION . . . . . . . . . . . . . . . . . . . 56 11 APPENDIX 1 . . . . . . . . . . . . . . . . . . . . 57 :::::::::::::: fgen.rno :::::::::::::: .FLAGS SPACE ~ ! Make sharp sign printable .KEEP ! Copy blank lines from input to output .HL 1 ^&Document Management System File Generator\& .HL ^&Introduction\& .P FILEGEN provides the documentation management system (DocMgr) with the capability to combine one or more files to create a single output file. The "source file" may contain directives which are processed by FILEGEN to generate the output file. These directives begin with the character "#" (sharp sign) in column one. The INCLUDE directive may be used to merge additional files into the output file. Other directives allow the file name (or the configuration identifier if the file is a component of a configuration item), the version number and the file modification date to be inserted into the output file. This provides a mechanism through which any file that is under configuration control can be uniquely identified when it is checked out of the configuration management system. .HL +1 ^&Command Format\& .LT ! take from the tool help message -- FileGen : Generate a target file from a source file -- 3.02-1.0 FileGen( Source : string; Output : string := ""; Catalog : string := ""; CI_Name : CI_ID_Type := "" ); Source: -- File name or name of a component of CI Output: -- Name of the output file (default is standard output) Catalog: -- Name of a CI Catalog (default is none) CI_Name: -- Name of a CI (default is none) .EL .HL ^&Parameters\& .P The OUTPUT parameter specifies the name of the file which is to contain the file to be generated. It is a host system file specification. .P The input file to be processed is specified by some combination of the remaining three parameters, depending on whether the input file is an ordinary text file, or a component within a configuration item. .P If the input file is an "ordinary file" (that is, one that has not been stored as as a component of a configuration item), then the SOURCE parameter is an ordinary file specification (on VMS, "USERMAN.SRC" or "[WORK.DOC]USERMAN.SRC", etc.), and CI_NAME is a null string. The CATALOG parameter is necessary only if an INCLUDE directive that specifies a CI component is encountered in one of the files being processed. .P If the source file is currently stored in an item library, then it cannot be processed by fileGen directly. Instead, it must be checked out of the library and processed as an ordinary file. .P Finally, if the source file is currently stored as a configuration item, then CATALOG is the name of the configuration item catalog, CI_NAME is the name of the configuration item, and SOURCE is the name of the file within this configuration item. .P The SOURCE parameter has the form of an ordinary host system file name. If the item is inside of an item library or a configuration item, it must be a simple file name (no directory path). .P The CATALOG parameter must be a valid Ada identifier. The CI_Name parameter is a valid Ada identifier followed by one or more spaces followed by a version number. See the section on the Catalog Manager for details on the version numbering scheme. .HL ^&Description\& .P FILEGEN has three basic functions: .LM +5 .LT 1. Extracting files from an Item Library or from a configuration item. 2. File inclusion 3. Substitutions: - Version ID - Date of last modification - CI_ID - ITEM_ID .EL .LM -5 .P The following are the directives that may be used in a file processed by FILEGEN. Lines that do not begin with a sharp sign (#) are simply copied to the output file. If the sharp sign appears twice in a row (in columns one and two), then the line is copied to the output file starting with column two (the first sharp sign is deleted). This makes it relatively easy to generate output files containing a sharp sign in column one, should the need arise. .P There are three kinds of directives: includes, substitutions, and definitions. The Include directive causes the contents of the designated file to be recursively processed by FILEGEN and copied to the output file. Substitution directives are evaluated and replaced by their values before the line is copied to the output file. Definitions assign string values to variables and do not generate any output. scope of a variable is limited to the file which defines it. .P In a directive, everything following a double dash is a comment (as in Ada) and is ignored. If a directive results in a line that is entirely blank, the line is not copied to the output file. Thus lines of the form .LT #-- <text> .EL are filtered from the input file. .P The syntax of the directives is as follows: .LT Directive = "Set" Variable ":=" StrVal -- Variable definition | "Include" "file" StrVal -- File inclusion | "Include" "il_item" StrVal, StrVal, VSpec -- File from item library | "Include" "ci_comp" StrVal, StrVal, VSpec -- File from CI Catalog | Expr -- Substitution StrVal = String | Variable VSpec = DottedNumber Expr = Primary -- Simple substitution | Primary Expr -- Concatenation Primary = StrVal -- String literal or variable | "Date" -- Replace with date of last modification | "CI" -- Replaced by CI name of this file | "ITEM" -- Replaced by Item name of this file | "Version" -- Replaced by Version Number of this file Variable = (an Ada identifier) .EL .HL ^&Variable Definitions\& .P A variable definition assigns a string value to an identifier. Subsequent uses of the variable are replaced by its value. If a variable is redefined, a warning message is issued. The scope of a variable is limited to the file that contains its definition. Variables must be defined before use. .P If a number of files are to be extracted from the same configuration item, it may be convenient to assign the configuration item name and version number to variable as in the following example: .LT #set CI := "System_Documentation" #set VNum := 5.3 #include CI_COMP CI, "Part_1", VNum #include CI_COMP CI, "Part_2", VNum #include CI_COMP CI, "Part_3", VNum .EL .P Then, it is a simple matter to change the definition of CI or VNum to extract the same files from a different configuration item or different version of the same item. .HL ^&The INCLUDE Directive\& .P There are three forms of the include directive. In all cases, the directive is replaced by the contents of the file that it specifies. The file can be either an ordinary host file, an item within an item library, or a file from a configuration item. To include an ordinary host system file, the following form of the INCLUDE directive is used: .LT #INCLUDE FILE <host system file name> .EL .P To include an item from within an item library, the name of the library, the name of the item, and the desired revision number must all be specified: .LT #INCLUDE IL_ITEM <library name> <item name> <version number> .EL The library name must be a valid Ada identifier. The item name is a host system file name, and the version number is a single digit number. .P Finally, to include an item from within a configuration item catalog, the name of the configuration item, the name of the file within that CI, and the desired revision number must all be specified: .LT #INCLUDE CI_COMP <CI name> <file name> <version number> .EL the CI name must be a valid Ada identifier. The file name is a simple host system file name, and the version number may contain several components to reflect branching within the configuration item catalog (eg. 1 or 1.1.3 or 1.2.3, etc.) .HL ^&Substitutions\& .P If a directive consists of a sequence of expressions, the value of each expression is simply copied to the output file and then the output line is terminated. .HL ^&Examples\& .P Assuming the following command is given to invoke FILEGEN .LT FILEGEN("USERMAN.FGN", "USERMAN.RNO"); .EL In this case, the file USERMAN.fgn will be processed to generate a file called USERMAN.RNO. No catalog or item library will be used. The following examples show how each directive might be used. .NF 1. Inserting the date of last modification into the output file: IN: #"This file last modified " Date OUT: This file last modified " 15-Jan-1985 15:33.32 2. Include a specified file: IN: #Include file "[DOC.WORK]INTRO.FGN" OUT: (Contents of the specified file [DOC.WORK]INTRO.FGN) 3. Variable definition IN: #SET Dir := "[WORK.DOC]" #"-- The value of DIR is: " Dir OUT: -- The value of DIR is: [WORK.DOC] 4. Substitutions of CI, Item, and Version IN: #"This is " Item " of " CI ", version " Version "." OUT: This is Item? of CI?, version Version? .F .P The above example shows that if the Item, CI, or Version substitutions are requested when an ordinary file is being processed, the strings "Item?", "CI?", and "Version?" are used. This allows a FILEGEN source file to be checked out before it becomes a component of a configuration item. .P Assuming the following command is given to invoke FILEGEN: .LT FILEGEN("TEST.ADAGEN", "TEST.ADA", "My_Catalog", "TestCI 3"); .EL The following show some directives and the associated output .NF 1. Inserting the CI_ID as a comment in the output file: IN: #"-- Version " Version " of " CI "." Item OUT: -- Version 3 of My_Catalog.TestCI 2. Inserting the CI_ID and date of last modification as a literal string in the output file: IN: #"Version_ID: constant string :=" #""" CI "." Item "(" Version ") of " Date """;" OUT: Version_ID: constant string := "My_Catalog.TestCI(3) of 8/12/85"; 3. Include a specified file: IN: #Include file "decls.ada" OUT: (Contents of the specified file) 4. Include a specified item (file) called "other.dat" from the same configuration item as is being processed: IN: #Include CI_COMP CI, "other.dat", Version OUT: (Contents of neighboring item OTHER.DAT) 5. Include a specified item from a different Item Library: IN: #Include IL_ITEM "Joes_IL", "other.dat", "3" OUT: (Contents of item OTHER.DAT version 3 from JOES_IL) 6. Include a specified item from some other CI: IN: #Include CI_COMP Joes_CI, other.dat, 3.2.7 OUT: (Contents of item OTHER.DAT from JOES_CI version 3.2.7) 7. Include two items from the same CI: IN: #Current_Version := "3.2.8" #Include CI_COMP Joes_CI, FIRST.DAT, Current_Version #Include CI_COMP Joes_CI, SECOND.DAT, Current_Version OUT: (Contents of item FIRST.DAT from JOES_CI version 3.2.8) (Contents of item SECOND.DAT from JOES_CI version 3.2.8) .F .HL ^&Notes\& .P There is no way to specify the "latest version" of an item in a CI. This is because 1) doing so would violate the requirement that it be possible to recreate any CI at any time and 2) since branches are allowed, the "latest version" is not well defined. :::::::::::::: install.mem :::::::::::::: INSTALLATION GUIDE To install the documetation system the HIF must be set up first. The first step is to decide where the root of the hif will be. This should be a directory, and where it is placed has no effect on the documentation system. After this directory is created set a logical variable 'HIF_DIRECTORY' to be the directory spec for it. You must also set the logical variable 'HIF_FDL' to be the full path name for fdl file shipped with the documentation system. The values for both these variables must also be given to the users in order for them to use the system. Once the variables are set you can run in this order: CRE_RM and CRE_RP. If prompted to 'Enter parameters:' just hit return. At this point the HIF is created. In order to run the documentation system one hif user must be added first. This is the hif user DOCMGR. If you wish to change the name you must also modify the name in DOCMGR.DAT and recompile. To add the user DOCMGR determine which directory the root of the documentation system should occupy, and then run ADD_USER giving it as parameters the directory path and "DOCMGR" for a user name. Now the only thing left to do is to define all the commands. A system manager could make system wide definitions, or each user could make the definitions in their login file. In the latter case you must inform the users where all the executables are. Catalogs and libraries are also HIF users and should it become necessary to remove a catalog there is the command DELTE_HIF_USER which takes a user name. It can also be used to delete users that leave without deleting themselves. It should be protected since it will allow any user on the computer delete any catalog or user. This procedure can also be used to delete libraries, but DELETE_LIBRARY has been provided for that case. DELETE_LIBRARY checks to make sure that the library is not outstanding from a catalog before deleting it, so it is preferable to use DELETE_LIBRARY for the safety checks. :::::::::::::: install.rno :::::::::::::: .LM 8 ! alternatively 0 .RM 75 ! alternatively 67 .PS ,75 ! alternatively 67 .STHL ,,2,0,,1,0,,! turns off section numbering, second level and lower not all caps .EUN ! enable underlining .FLAGS ACCEPT % ! Make underscore a printable character, we don't need overstrike .T Installation Guide (Draft) .HL Installation Guide .SK .P To install the documetation system the HIF must be set up first. The first step is to decide where the root of the HIF will be. This should be a directory, and where it is placed has no effect on the documentation system. After this directory is created set a logical variable 'HIF_DIRECTORY' to be the directory spec for it. You must also set the logical variable 'HIF_FDL' to be the full path name for FDL file shipped with the documentation system. The values for both these variables must also be given to the users in order for them to use the system. .P Once the variables are set you can run in this order: CRE_RM and CRE_RP. If prompted to 'Enter parameters:' just hit return. At this point the HIF is created. .P In order to run the documentation system one hif user must be added first. This is the hif user DOCMGR. If you wish to change the name you must also modify the name in DOCMGR.DAT and recompile. To add the user DOCMGR determine which directory the root of the documentation system should occupy, and then run ADD_USER giving it as parameters the directory path and "DOCMGR" for a user name. Now the only thing left to do is to define all the commands. A system manager could make system wide definitions, or each user could make the definitions in their login file. In the latter case you must inform the users where all the executables are. .P Catalogs and libraries are also HIF users and should it become necessary to remove a catalog there is the command DELTE_HIF_USER which takes a user name. The name to give it to delete a catalog is the catalog name. It can also be used to delete users that leave without deleting themselves. It should be protected since it will allow any user on the computer delete any catalog or user. This procedure can also be used to delete libraries, but DELETE_LIBRARY has been provided for that case. DELETE_LIBRARY checks to make sure that the library is not outstanding from a catalog before deleting it, so it is preferable to use DELETE_LIBRARY for the safety checks. :::::::::::::: libmgr.rno :::::::::::::: .PAGE .HEADER LEVEL 1^&Item Library Manager\& .BLANK .HEADER LEVEL 2^&Description\& .BLANK .PARAGRAPH The Item Library Manager consists of a set of functions to manage a library of related files (items) called an item library. It will provide configuration control over the items and maintain multiple versions of the same item. An item library is a working copy of a configuration item (CI) and may have associated with it, properties to describe itself (See Catalog Manager for details on CI's and properties). The following commands are provided in the Item Library Manager: .BLANK .LS 0, "o" .LE LIBRARY_MANAGER .LE CREATE_LIBRARY .LE DELETE_LIBRARY .LE COPY_LIBRARY .LE LIST_LIBRARY .LE CREATE_ITEM .LE FETCH_ITEM .LE RETURN_ITEM .LE LIST_ITEM .ELS 0 .BLANK 2 .HEADER LEVEL 2^&CREATE_LIBRARY\& .LITERAL -- CREATE_LIBRARY : Create an Item Library -- 3.02-1.0 subtype LIBRARY_NAME is STRING; subtype DIRECTORY_SPEC is STRING; procedure CREATE_LIBRARY( LIBRARY : in LIBRARY_NAME; DIRECTORY : in DIRECTORY_SPEC ); -- LIBRARY : Name of the item library to be created -- DIRECTORY : Name of directory to be used by this library .END LITERAL .PARAGRAPH The CREATE_LIBRARY command creates an item library with the specified name. The library name must be an Ada identifier. The directory may be any string but must be a valid directory specification for the file system in which the Item Library Manager resides. All items/information of this item library will be contained in the specified directory. The Item Library Manager does NOT provide protection for this directory except in the context of item libraries. It is recommended that no files/attributes be changed/deleted in this directory. Failure to adhere to this may cause the entire document management system to be corrupted. .BLANK 2 .HEADER LEVEL 2^&DELETE_LIBRARY\& .LITERAL -- DELETE_LIBRARY : Delete an Item Library -- 3.02-1.0 subtype LIBRARY_NAME is STRING; procedure DELETE_LIBRARY( LIBRARY : in LIBRARY_NAME ); -- LIBRARY : Name of the item library to be deleted .END LITERAL .PARAGRAPH The DELETE_LIBRARY command deletes an existing item library. Only the owner of a library may delete the library and only if the library is not pending a return into a catalog as a CI (See Catalog Manager for details of RETURN_CI function). .BLANK 2 .HEADER LEVEL 2^©_LIBRARY\& .LITERAL -- COPY_LIBRARY : Copy an Item Library to Another Item Library -- 3.02-1.0 subtype LIBRARY_NAME is STRING; subtype DIRECTORY_SPEC is STRING; type COPY_MODE is (CURRENT, FULL); procedure COPY_LIBRARY( FROM_LIBRARY : in LIBRARY_NAME; TO_LIBRARY : in LIBRARY_NAME; TO_DIRECTORY : in DIRECTORY_SPEC; MODE : in COPY_MODE := CURRENT ); -- FROM_LIBRARY : Name of the item library to be copied -- TO_LIBRARY : Name of the new item library -- TO_DIRECTORY : Name of directory to be used by the new library -- MODE : Copy option: -- CURRENT : copy only the current version of items -- FULL : copy all versions of items .END LITERAL .PARAGRAPH The COPY_LIBRARY command copies an existing item library to another item library. The new library name must be an Ada identifier. All attributes except library ownership are copied from the existing library. A library may be copied only if there are not items within the library pending a return. The Mode option specifies if all versions of all items in the library are copied (FULL) or only the latest version of all items are copied (CURRENT). .BLANK 2 .HEADER LEVEL 2^&LIST_LIBRARY\& .LITERAL -- LIST_LIBRARY : List Libraries Owned by User -- 3.02-1.0 subtype USER_NAME is STRING; subtype LIBRARY_NAME is STRING; procedure LIST_LIBRARY( OWNER : in USER_NAME := "owner_name"; LIBRARY : in LIBRARY_NAME := "*" ); -- OWNER : Name of the library owner -- LIBRARY : Name of the library .END LITERAL .PARAGRAPH The LIST_LIBRARY command lists all libraries that satisfy the condition given by the ownership and name of the libraries. Both the library ownership and name may contain wildcard character(s) "%*". .BLANK 2 .HEADER LEVEL 2^&CREATE_ITEM\& .LITERAL -- CREATE_ITEM : Create an Item in the Item Library -- 3.02-1.0 subtype LIBRARY_NAME is STRING; subtype FILE_NAME is STRING; procedure CREATE_ITEM( LIBRARY : in LIBRARY_NAME; FILE : in FILE_NAME; HISTORY : in STRING ); -- LIBRARY : Name of the item library -- FILE : Name of the file to be checked into the item library -- HISTORY : Description/reason for this item .END LITERAL .PARAGRAPH The CREATE_ITEM command is used to create an item in the item library from a given file. The item name will be the same as the file name and must not already exist in the item library. The History may be any character string and will be stored in the item library associated with the created item. .BLANK 2 .HEADER LEVEL 2^&FETCH_ITEM\& .LITERAL -- FETCH_ITEM : Fetch an Item from an Item Library -- 3.02-1.0 subtype LIBRARY_NAME is STRING; subtype ITEM_NAME is STRING; subtype VERSION is STRING; type FETCH_MODE is (NO_UPDATE, UPDATE); procedure FETCH_ITEM( LIBRARY : in LIBRARY_NAME; ITEM : in ITEM_NAME; VERSION : in VERSION := ""; MODE : in FETCH_MODE := NO_UPDATE ); -- LIBRARY : Name of the item library -- ITEM : Name of the item to be fetched from the item library -- VERSION : Version specification -- MODE : Fetch mode: -- NO_UPDATE : check out an item for read only -- UPDATE : check out an item for update .END LITERAL .PARAGRAPH The FETCH_ITEM command is used to check an item out of the item library. The checked out item will be a file in the current directory with the item name as its file name. The Mode specifies whether the item is to be checked out as read only (NO_UPDATE) or for updating and eventual return to the item library (UPDATE). Only the current version may be checked out for UPDATE provided that it is not already checked out for UPDATE. The version specification may be any numeric in string format (eg. "3") or a null string for the current version. .BLANK 2 .HEADER LEVEL 2^&RETURN_ITEM\& .LITERAL -- RETURN_ITEM : Return a File to an Item Library -- 3.02-1.0 subtype LIBRARY_NAME is STRING; subtype FILE_NAME is STRING; procedure RETURN_ITEM( LIBRARY : in LIBRARY_NAME; FILE : in FILE_NAME; HISTORY : in STRING ); -- LIBRARY : Name of the item library -- FILE : Name of the file to be returned to the item library -- HISTORY : Description/reason for the change(s) in this item .END LITERAL .PARAGRAPH The RETURN_ITEM command is used to check a file back into the item library as a new version of an item previously checked out (see FETCH_ITEM). The History may be any character string and will be stored in the item library associated with this new version of an item. .BLANK 2 .HEADER LEVEL 2^&LIST_ITEM\& .LITERAL -- LIST_ITEM : List Item(s) in the Item Library -- 3.02-1.0 subtype LIBRARY_NAME is STRING; subtype ITEM_NAME is STRING; subtype VERSION is STRING; type LIST_MODE is (LONG, SHORT); procedure LIST_ITEM( LIBRARY : in LIBRARY_NAME; ITEM : in ITEM_NAME := "*"; VERSION : in VERSION := ""; MODE : in LIST_MODE := SHORT ); -- LIBRARY : Name of the item library -- ITEM : Name of the item to list -- VERSION : Version specification -- MODE : List mode: -- SHORT : list item/version name(s) only -- LONG : list attributes as well as item/version name(s) .END LITERAL .PARAGRAPH The LIST_ITEM command lists item(s) in the item library that satisfies the condition specified by Item and Version. Both Item and Version may contain wildcard character(s) "%*". The Mode specifies whether the list is to contain only the item name and version (SHORT) or item name, version, and associated attributes (LONG). .BLANK 2 .HEADER LEVEL 2^&LIBRARY_MANAGER : Interactive Library Manager\& .LITERAL -- LIBRARY_MANAGER : Interactive Library Manager Tool -- 3.02-1.0 subtype LIBRARY_NAME is STRING; procedure LIBRARY_MANAGER( LIBRARY : in LIBRARY_NAME := ""; PROMPT : in STRING := "" ); -- LIBRARY : Name of the item library -- PROMPT : Prompt string .END LITERAL .PARAGRAPH This command invokes the interactive library management tool. The item library name if given must be an Ada identifier. The PROMPT may be any string and will appear as a prompt for the interactive library manager. The following interactive commands are provided: .BLANK .LS 0, "o" .LE CREATE_LIBRARY .LE DELETE_LIBRARY .LE COPY_LIBRARY .LE LIST_LIBRARY .LE CREATE_ITEM .LE FETCH_ITEM .LE RETURN_ITEM .LE CANCEL_ITEM .LE LIST_ITEM .LE DELETE_ITEM .LE PURGE_ITEM .LE RENAME_ITEM .LE RENAME_VERSION .LE SHOW_HISTORY .LE ADD_PROPERTY .LE DELETE_PROPERTY .LE MODIFY_PROPERTY .LE LIST_PROPERTY .LE ENTER_LIBRARY .LE HELP .LE EXIT .ELS 0 .PARAGRAPH The HELP command shows brief descriptions of all Interactive Library Manager commands. .PARAGRAPH The EXIT command is used to terminate the Interactive Library Manager session. .PARAGRAPH The following commands have the same function and command syntax as described immediately above: .BLANK .LITERAL CREATE_LIBRARY DELETE_LIBRARY COPY_LIBRARY LIST_LIBRARY .END LITERAL .PARAGRAPH The following commands have the same function as described immediately above but the command syntax differs in that no library specifications are given: .BLANK .LITERAL CREATE_ITEM FETCH_ITEM RETURN_ITEM LIST_ITEM .END LITERAL .BLANK 2 .HEADER LEVEL 3^&CANCEL_ITEM\& .LITERAL -- CANCEL_ITEM : Cancel a Pending Return for an Item in the Item Library -- 3.02-1.0 subtype ITEM_NAME is STRING; procedure CANCEL_ITEM( ITEM : in ITEM_NAME ); -- ITEM : Name of the item to cancel the pending return .END LITERAL .PARAGRAPH The CANCEL_ITEM command cancels a return pending state of an item in the item library without returning the file back into the item library. The item must be checked out for update to be canceled. .BLANK 2 .HEADER LEVEL 3^&DELETE_ITEM\& .LITERAL -- DELETE_ITEM : Delete Item(s) in an Item Library -- 3.02-1.0 subtype ITEM_NAME is STRING; subtype VERSION is STRING; procedure DELETE_ITEM( ITEM : in ITEM_NAME; VERSION : in VERSION := "" ); -- ITEM : Name of the item(s) to be deleted in the item library -- VERSION : Version specification .END LITERAL .PARAGRAPH The DELETE_ITEM command deletes item(s) from the item library. Both Item and Version specification may contain wildcard character(s) "%*". All items/versions that satisfy the specifications and whose ownership requirements are satisfied are deleted from the item library. .BLANK 2 .HEADER LEVEL 3^&PURGE_ITEM\& .LITERAL -- PURGE_ITEM : Purge Item(s) in an Item Library -- 3.02-1.0 subtype ITEM_NAME is STRING; procedure PURGE_ITEM( ITEM : in ITEM_NAME ); -- ITEM : Name of the item(s) to be purged in the item library .END LITERAL .PARAGRAPH The PURGE_ITEM command deletes all but the current version(s) of item(s) from the item library. Item specification may contain wildcard character(s) "%*". All items that satisfy the specification and whose ownership requirements are satisfied will have all but their highest version(s) deleted. .BLANK 2 .HEADER LEVEL 3^&RENAME_ITEM\& .LITERAL -- RENAME_ITEM : Rename Item in an Item Library -- 3.02-1.0 subtype ITEM_NAME is STRING; procedure RENAME_ITEM( FROM_ITEM : in ITEM_NAME; TO_ITEM : in ITEM_NAME ); -- FROM_ITEM : Name of the item to be renamed in the item library -- TO_ITEM : New item name .END LITERAL .PARAGRAPH The RENAME_ITEM command renames an item in the item library. The item name specification may not contain wildcard character "%*". The validity of the new item name is not checked by RENAME_ITEM. Invalid item name (ie. name that may not conform to the file name specification of the file system on which the library manager resides) will make the item unretrievable by FETCH_ITEM operation which will attempt to create an external file with the same name as the item name being fetched. .BLANK 2 .HEADER LEVEL 3^&RENAME_VERSION\& .LITERAL -- RENAME_VERSION : Rename Version of Item(s) in an Item Library -- 3.02-1.0 subtype ITEM_NAME is STRING; subtype VERSION is STRING; procedure RENAME_VERSION( ITEM : in ITEM_NAME; FROM_VERSION : in VERSION; TO_VERSION : in VERSION ); -- ITEM : Name of the item(s) to be renamed in the item library -- FROM_VERSION : Version of item(s) to be renamed -- TO_VERSION : New version of item(s) .END LITERAL .PARAGRAPH The RENAME_VERSION command renames a version of item(s) in the item library. The version specification may not contain wildcard character "%*". The current version may be specified as a null string "". The item specification may contain wildcard characters "%*". Inappropriate usage of this command may cause regression in the item versions. .BLANK 2 .HEADER LEVEL 3^&SHOW_HISTORY\& .LITERAL -- SHOW_HISTORY : Show History of Item(s) in an Item Library -- 3.02-1.0 subtype ITEM_NAME is STRING; subtype VERSION is STRING; procedure SHOW_HISTORY( ITEM : in ITEM_NAME := "*"; VERSION : in VERSION := "" ); -- ITEM : Name of the item to list -- VERSION : Version specification .END LITERAL .PARAGRAPH The SHOW_HISTORY command lists all history descriptions associated with all version(s) of item(s) that satisfy the condition specified by Item and Version. Both Item and Version may contain wildcard character(s) "%*". The current version is specified by a null string "". .BLANK 2 .HEADER LEVEL 3^&ADD_PROPERTY\& .LITERAL -- ADD_PROPERTY : Add a Property Keyword/Value to the Item Library -- 3.02-1.0 procedure ADD_PROPERTY( KEYWORD : in STRING; VALUE : in STRING ); -- KEYWORD : Property keyword -- VALUE : Property value .END LITERAL .PARAGRAPH The ADD_PROPERTY command is used to associate a new keyword/value property description to an item library. The property keyword to be added must not exist. Both the keyword and the value must be an Ada identifier. .BLANK 2 .HEADER LEVEL 3^&DELETE_PROPERTY\& .LITERAL -- DELETE_PROPERTY : Delete a Property Keyword from the Item Library -- 3.02-1.0 procedure DELETE_PROPERTY( KEYWORD : in STRING ); -- KEYWORD : Property keyword .END LITERAL .PARAGRAPH The DELETE_PROPERTY command is used to delete a property description associated with an item library. The property keyword to be delete must exist. The keyword must be an Ada identifier. .BLANK 2 .HEADER LEVEL 3^&MODIFY_PROPERTY\& .LITERAL -- MODIFY_PROPERTY : Change a Property Keyword/Value in the Item Library -- 3.02-1.0 procedure MODIFY_PROPERTY( KEYWORD : in STRING; VALUE : in STRING ); -- KEYWORD : Property keyword -- VALUE : Property value .END LITERAL .PARAGRAPH The MODIFY_PROPERTY command is used to change the value of a property description keyword associated with an item library. The property keyword whose value is to be changed must exist. Both the keyword and the value must be an Ada identifier. .BLANK 2 .HEADER LEVEL 3^&LIST_PROPERTY\& .LITERAL -- LIST_PROPERTY : List Property Keyword/Value in the Item Library -- 3.02-1.0 procedure LIST_PROPERTY( KEYWORD : in STRING := "*" ); -- KEYWORD : Property keyword .END LITERAL .PARAGRAPH The LIST_PROPERTY command lists keyword/value property description(s) associate with an item library. The keyword may contain wildcard character(s) "%*" but otherwise must be an Ada identifier. .BLANK 2 .HEADER LEVEL 3^&ENTER_LIBRARY\& .LITERAL -- ENTER_LIBRARRY : Enter a Given Item Library -- 3.02-1.0 subtype LIBRARY_NAME is STRING; procedure ENTER_LIBRARY( LIBRARY : in LIBRARY_NAME ); -- LIBRARY : Name of the item library .END LITERAL .PARAGRAPH The ENTER_LIBRARY command sets the given library as a current item library. All subsequent commands will operate on the given library. A null library name resets the current library to the library for which the Interactive Library Manager was invoked. .PAGE .HEADER LEVEL 2^&Examples\& .PARAGRAPH The following sequence of commands describe a typical item library operations for creating and manipulating an item library. Assume that there are three (3) files called FILE1.ADA, FILE2.SPC, and FILE2.BDY and one wishes to create an item library PROJECT_LIBRARY. .BLANK .LITERAL CREATE_LIBRARY ("PROJECT_LIBRARY", "[.PLIB]"); -- create a library PROJECT_LIBRARY in a directory -- PLIB relative to the current directory (VAX/VMS notation) LIBRARY_MANAGER ("PROJECT_LIBRARY", "=>"); -- enter the interactive library manager for PROJECT_LIBRARY -- prompt string is => => ADD_PROPERTY ("PROGRAMMER", "JOHN"); => ADD_PROPERTY ("LANGUAGE", "ADA"); => ADD_PROPERTY ("PROJECT", "XXX_123"); -- give the library properties with appropriate values => CREATE_ITEM ("FILE1.ADA", "Description of FILE1"); => CREATE_ITEM ("FILE2.SPC", "Description of FILE2 Spec"); => CREATE_ITEM ("FILE1.ADA", "Description of FILE2 Body"); -- create items in the library with descriptions -- associated with each item EXIT; -- exit the interactive library manager -- -- now there is a need to change FILE2.BDY -- FETCH_ITEM ("PROJECT_LIBRARY", "FILE2.BDY", UPDATE); -- check FILE2.BDY out of the library for update -- change FILE2.BDY using any editor RETURN_ITEM ("PROJECT_LIBRARY", "FILE2.BDY", "Change description"); -- check FILE2.BDY back into the library -- now there will be two versions of FILE2.BDY in the library .END LITERAL .BLANK 2 .HEADER LEVEL 2^&Bugs\& .PARAGRAPH External interrupt(s) during item library management operations may cause abnormal behavior. .PAGE :::::::::::::: paginate.rno :::::::::::::: .PAGE .HEADER LEVEL 1^&Document Printer\& .BLANK .HEADER LEVEL 2^&Description\& .BLANK .PARAGRAPH The Document Printer produces a page separated output file from any number of input files. The page header and footer lines may be specified as well as the output page size, margin setting, and line numbering. .BLANK .HEADER LEVEL 2^&Document Printer Command Format\& .LITERAL -- PAGINATE : Formats file(s) as specified -- 3.02-1.00 subtype FILE_NAME is STRING; type SOURCE_LIST is array (POSITIVE range <>) of FILE_NAME; subtype PAGE_TYPE is INTEGER range 1 .. 999; subtype MARGIN_TYPE is INTEGER range 0 .. 20; type SWITCH is (ON, OFF); procedure PAGINATE( SOURCE_LIST : in SOURCE_LIST; OUTPUT : in FILE_NAME; HEADER : in STRING := "~F(L50) ~D ~T Page ~P(R3)"; FOOTER : in STRING := ""; PAGE : in PAGE_TYPE := 60; MARGIN : in MARGIN_TYPE := 0; NUMBER : in SWITCH := OFF ); -- SOURCE_LIST : List of file name(s) to be formatted -- OUTPUT : Output file name (defaults to standard output) -- HEADER : Header text -- FOOTER : Footer text -- PAGE : Number of lines per page (excluding header/footer) -- MARGIN : Left margin size -- NUMBER : Line numbering .END LITERAL .PARAGRAPH The header/footer text may contain substitution sequence(s) as place holder(s) for actual data to be inserted in the output file. The substitution sequence is defined by an escape character tilde (%~) followed by a substitution character and may be followed by an optional alignment specification consisting of an alignment character and a numeric field size. The general format of the substitution sequence is %~S(Ann) where S is the substitution character and A is the alignment character followed by a number nn. .PAGE The valid substitution characters are: .BLANK .LITERAL F : output external file name P : current page number D : current date (eg. 03/15/86) C : current calendar date (eg. March 15, 1986) T : current time (eg. 04:53:32) .END LITERAL .BLANK .PARAGRAPH The valid optional alignment character A are: .BLANK .LITERAL L : left align the text R : right align the text C : center the text .END LITERAL .BLANK The nn following the alignment character specifies the number of spaces the text will displace in the header/footer text. The case is not significant after the escape character tilde (%~). If the escape character is followed by any character other than a valid substitution character the tilde will not be printed and no substitution is performed. To print a tilde character in the output header/footer two (2) consecutive tilde characters must be written in the header/footer specification. .PAGE .HEADER LEVEL 2^&Examples\& .PARAGRAPH The following example takes three (3) files FILE1..DAT, FILE2..DAT, and FILE3..DAT as input (SOURCE_LIST) and creates a paginated output file FILES..OUT (OUTPUT). The header (HEADER) consists of the output file name left aligned to 60 characters followed by the date and time. The footer (FOOTER) consists of the page number centered in the middle of the page. The whole text is offset (MARGIN) by five (5) characters at the left margin. .BLANK .LITERAL PAGINATE ( SOURCE_LIST => ("FILE1.DAT", "FILE2.DAT", "FILE3.DAT"), OUTPUT => "FILES.OUT", HEADER => "~F(L60) ~D ~T", FOOTER => "~P(C80)", MARGIN => 5); .END LITERAL .PAGE .HEADER LEVEL 2^&Bugs\& .PARAGRAPH There are no known bugs. .PAGE :::::::::::::: release.nts :::::::::::::: 11-APR-86 Initial release built on Super-HIF. Know Super-HIF problem : No mutiple processes in a single HIF at one time. :::::::::::::: title.mem :::::::::::::: DOCUMENTATION SYSTEM USER GUIDE