|
Using the CFS file information system, a descriptive text can be attached to any file, job variable or library element. This feature allows book keeping for each file. The information texts stored in the system can be retrieved and updated at any time. All information texts for files, job variables and library elements are stored in the file catalogues created and managed by CFS.
For the storage of information texts of files or library elements, CFS creates separate information catalogues. This is done during the first creation of an information text (Action Code IM).
If you do not provide an explicit file command, the name of the CFS information catalogue is constructed in the following way:
CFS.INF Information catalogue for files of the own user-id.
CFS.INF.JV Information catalogue for job variables of the own user-id.
lib.INF Information catalogue for elements of library lib.
Files and job variables have a separate information catalogue for each user-id. Also, each library has a separate information catalogue.
Using the file command (LINK=INFO) the user may assign the name of a specific information catalogue.
Input of texts is usually done in free form mode. CFS prompts you with an empty screen where you can enter the information texts.
Alternatively, you may enter the information texts in a formatted way controlled by masks. These INF-masks must exist in a central INF-format catalogue (ISAM-file). They are accessed via a 1- to 3-character format name. By default the INF-format catalogue has the name $TSOS.CFS.INF.FORMAT. You may assign your own format catalogue via a file command: /FILE file, LINK=IFORMAT.
If new texts are entered, the selection of a format is done by appending the format name f (1-3 characters) to the Action Code IM/IA (Information Modify / Information Add). The system administrator may change the CFS default settings to attach a fixed default format x to new texts (implicit IMx).
Action Codes for Creation and Retrieval of CFS Information catalogues
I Inform. Display of information text belonging to a data object (file / job variable / library element).
IM [f] Information Modify. Create or update information text.
f Only for creation of a information text: a 1- to 3-character mnemonic name of the mask used for entry of the information text. These masks and their mnemonic names must have been entered by the system manager into the central format catalogue CFS.INF.FORMAT.
IA [f] Information Add. An additional page of information text is appended to the existing text.
f Format name for data entry of a information text (1-3 bytes).
If the Action Code is issued an no information text exists, it has the same effect as IM (creation).
II [f] Information Insert. An additional page is inserted into the information text. The new page is inserted behind the last page that was created with the same format.
f Format name for data entry of a information text (1-3 bytes).
Note: If the Action Code is given and no information text exists, it has the same effect as IM (creation).
If the format specified with the II Action Code does not occur in the information text, the new page is appended to the end of the documentation (same effect as IA: Information Add).
IE Information Erase. Deleting of a information text for the data object.
IEQ Information Erase with Query. The single pages of the information text are displayed. Each information page displayed can be deleted by pressing the ENTER-key. The displayed information page is kept and not deleted by pressing the K3 key. In both cases the next page is displayed. The display process can be cancelled by pressing the K1 key.
IC Information Copy. Copying of an entire information text. You are prompted for the name of an existing data object. The copied information is offered for modification (implicit IM) automatically.
Notes:
If you specified a non existent format name with the Action Codes IM and IA, CFS will display an error message and continue with format free data entry.
If a default format was defined by the system administrator, but you want to enter the documentation in format free mode, you may achieve this by specifying a non existing format name f in Action Code IM or IA.
The commands CAP/LOW may be used to influence the translation of lower case letters during creation or modification of information texts (IM).
Default: CAP. Lower case letters are translated into upper case letters.
With the command I FORM=f the user may define an individual format that is used by default for new information texts ( Action Codes IM/IA without explicit format specification ).
With the User Option INF all files / job variables / library elements may be found for which documentations exist / do not exist.
Selection mask, field USER OPTION:
INF informs, if a documentation exists in the CFS information catalogue for a file / job variable / library element. The name of the format used for data entry will also be displayed.
Selection parameter: [Y | N | S] [, FORM=xxx] [, 'string']
Y | N Information text available ? Yes/No
S same as Y. In addition the first 15 bytes of the information text are shown in the file list.
FORM=xxx Selection according to the format used for data entry.
'string' Selection of all files or library elements, where the specified search string is found in the attached information text.
If parameter FORM= or a search string was specified the first selection parameter is automatically assumed as 'Y' and may be omitted. All parameters must be separated by comma.
How to store formats into the central INF format catalogue
It is the duty of the system administrator, to move the formats required for the entry of information texts into the INF-format catalogue of CFS. We propose the following steps:
1) Create the required format using IFG/FORMPLAG.
2) Open a CFS-connection and activate logging only for output: LOG file,O
3) Call IFG and select function 02: 'Display format' (sub function: 'format as during use') resp. call FORMPLAG.ETH and select the test function: .T (display map). The format will be captured in the LOG-file specified in step 2).
4) Terminate IFG / FORMPLAG.ETH and deactivate logging with command NLOG.
5) Display the so created LOG file using CFS-display: I file,D. Switch into modify mode via command M.
6) Delete all records in the LOG file except the protocol record of the IFG-/ FORMPLAG-format. You may delete a data record by overwriting the first position of the ISAM-key with the character 'E' (Eliminate Record).
7) Transfer this single remaining record into the central format catalogue. For this purpose CFS provides a special command:
(ADDFORM) file [, f] [, format-cat]
file Name of the LOG-file into which the required format was recorded. The file must contain only one record.
f format name (1-3 characters) under which the map is stored into the format catalogue.
format-cat Name of the catalogue into which the current format shall be stored. If no name was specified, the name of the central format catalogue ($TSOS.CFS.INF.FORMAT) is used by default. The name of the central format catalogue can be customized via module CFSMAIN according to the requirements of the operating centre.
Writing the documentations stored in the INF-catalogue into an EDT file (Export)
The INF-catalogue with its stored information texts belonging to different files or library elements can be processed by CFS only. The reason is, that data records contained in the INF-catalogue can have a length of up to 2048 characters. The key length of the ISAM-file is 44.
Via command FC2 EXP:... the user is able to export the whole content of an information catalogue into a normal EDT file. This file can then be processed, e.g. with EDT using @ON&C'...'T'...'.
The exported EDT file may also be printed out.
catalogue Name of the CFS information catalogue (CFS.INF / library.INF).
file Name of the target SAM file (EDT format).
Creating an INF-catalogue from an EDT file (Import)
FC2 IMP: file , catalogue [, MERGE]
The command FC2 IMP:... acts as the counterpart to the export command described above. Exoprted INF-catalogues that have been modified using EDT, can be imported again with this command. The EDT format is converted into the CFS internal format of the information catalogue.
file Name of the SAM file containing the information texts for the information catalogue.
catalogue Name of the catalogue to be created. (CFS.INF / library.INF).
MERGE The data items contained in the SAM file are merged into an existing information catalogue.
Default: A new information catalogue is created.
Notes:
You may process an exported INF-catalogue with EDT and import it afterwards. The import will overwrite all existing information in the INF-catalogue. During the editing of the exported catalogue (SAM file), the following rules have to be observed:
If you want to insert information for an additional data object, e.g. a description of file ABC.XYZ, you have to insert two records:
$NAME = ABC.XYZ
$
These records are followed by records containing the information text. If the information text exceeds 22 lines, you may want to program a format change between the second and the 22nd line. To do so, insert a control record:
'$$' before the first record to appear on a new screen.
Conversion INF-catalogue <---> PLAM library
FC2 CON: file1 [, file2] [, P]
Conversion ISAM --> PLAM
file1 CFS information catalogue (ISAM-file).
file2 PLAM library (target).
If file2 is not specified, a temporary library is created that will be copied to file1 at the end of the conversion.
The content of the information catalogue is transferred to PLAM library file2. This library may already exist. If not, a new library is created. For each file description one element in library file2 is created: S/xxxx. If the file description consists of more than one screen page (more than one ISAM-record), the corresponding data in the library element are separated by records containing $NEW PAGE.
Conversion PLAM --> ISAM
file1 PLAM library.
file2 CFS information catalogue. If file2 was not specified, a temporary information catalogue is created that will overwrite the PLAM library file1 at the end of the conversion.
The content of the elements in PLAM library file1 is transferred into information catalogue file2. The information catalogue may already exist. If not, a new information catalogue is created. For each library element t/xxxxx one or more ISAM records with key xxxxx are written into the information catalogue file2. More than one record is written, if the library element contains separating control records $NEW PAGE.
P If this option is specified, also the element type is transferred into the ISAM-key of the records in the information catalogue. An INF-catalogue created in this way can only be used for the documentation of elements of a PLAM library.
An information catalogue can be printed as an exported SAM file using the PRINT command (without SPACE=E).
Another possibility is the following:
1) Select all data objects for which an information text exists with the USER OPTION : INF Y.
2) Create a documentation file containing the names of the data objects and merge the full information texts into that file, using the command DOC file,INF, ALL;A
The so created file can be printed with option SPACE=E.
For the files / library elements / job variables marked with X, the documentations are copied from catalogue cat1 into catalogue cat2.
UPD cat2 is opened with OPEN=INOUT instead of OPEN=OUTPUT (default).
The Variable Action ONXICOPY ... is suitable for reorganising INF-catalogues. Often the INF catalogues still contains information texts for already deleted data objects. The data objects having information texts in the INF-catalogue can be selected with the User Option: INF Y. On the selected data objects the Variable Action ON&ICOPY cat1,cat2 is applied. The documentation for all still existing data objects are then transferred into a new INF-catalogue. The old catalogue (e.g. CFS.INF) can than be overwritten with the new catalogue.
Retaining the documentation for deleted data objects.
The original, not reorganised INF-catalogue is first exported to a SAM file using the command FC2 EXP:catalogue,file-a. Afterwards the INF-catalogue is reorganised (see above). Then the new, reorganised catalogue is also exported (FC2 EXP: catalogue,file-n). Both export files are now compared using the CFS-command COMP file-a, file-n. The resulting difference protocol contains the information texts for all deleted objects.