The FM function enables you to maintain the Com-plete file catalog established in the COMSYS Data Set.
Application programs refer to files by DD/DLBL names. To establish the link between these names and the corresponding data sets, all DD/DLBL names referenced by application programs must be declared ("cataloged") to Com-plete using this subfunction.
The declaration includes the data set name, disposition (z/OS only), the name of the VSAM user catalog (z/VSE only), and other information (see below). The data set is allocated to Com-plete dynamically when an OPEN request is issued against the appropriate DD/DLBL name and deallocated when Com-plete is stopped, or when the file is closed explicitly using the CLOSE or BATCH subfunctions of UUTIL FM.
In comparison with the permanent data set allocation by JCL DD/DLBL statements used with previous versions of Com-plete, this mechanism provides maximum flexibility of data set access by BATCH jobs and for data set maintenance (backup, restore, reallocation, rename, etc.) without the need of restarting Com-plete.
The file declaration defines all parameters necessary for Com-plete to open the file. Options specified for a file in an application program are ignored. Instead, Com-plete uses the parameters defined via UUTIL FM to build control blocks and buffers once per DD/DLBL name. However, the parameters specified here for a file must be consistent with the file processing techniques used by application programs.
All online programs referring to a given DD/DLBL name share the same control blocks and buffers. This allows efficient use of resources in the system, but can also significantly influence performance. Therefore, careful choice of parameter values is recommended for files referenced frequently and by a large number of terminal users.
The File Catalog Maintenance function records the status and processing options of online files to be manipulated using one of the following access methods:
Indexed-Sequential Access Method (ISAM, z/OS only);
Basic Direct Access Method (BDAM, z/OS only);
Virtual storage Access Method (VSAM).
The addition of records to ISAM files in the online environment is not recommended because of the high overhead operation involving use of ISAM overflow areas. This, in turn, requires periodic reorganization of the ISAM file.
The use of the ADD option imposes two restrictions on programs accessing ISAM files:
The file must be allocated with DISP=OLD in Com-plete. Note that sharing of an ISAM file between Com-plete and another job step is not supported when records are added.
You can use the following alternatives to circumvent these restrictions:
Instead of the ADD option, keep enough dummy records in the data set and update those records.
If the ADD option is required, split the ADD processing of the file into a separate program and use a FETCH or ATTACH function to invoke it. This allows most of the processing to take place in any thread, thus reducing the overhead of thread- locking all processing to a single thread.
The ADD option has no meaning for BDAM files because BDAM files are preformatted.
Com-plete extends BDAM support by allowing blocked BDAM files. This support is governed by the LRECL keyword in the DD statement or the data set attributes as recorded by the operating system. Com-plete computes the block number, reads it, and passes back the requested record from the block.
Note:
Only relative record access is supported with this technique.
The way a VSAM cluster is created (by Access Method Services) and defined to Com-plete (File Catalog utility) can have a significant impact on performance and storage utilization within Com-plete.
It is recommended that you select a small control interval size when establishing the cluster in order to minimize buffer requirements and the impact of control intervals being held for update requests.
Com-plete provides optional support of establishing a VSAM local shared resource pool during system initialization. This support allows many VSAM clusters to share buffer pool and control block resources, thus minimizing storage requirements and the chance that storage may not be available to open a new cluster at first access. This resource pool is configured by the system programmer using the VSAMBUFFERS, VSAMHIPERSPACE (z/OS only), VSAMRPL and VSAMFIX sysparms.
Using the shared resource pool is recommended when it is not
necessary - for performance reasons - to dedicate buffers and control blocks to
the file. To use the shared resource pool, be sure that the file to be accessed
can use the buffer pool defined by the VSAMBUFFERS sysparm and that all
programs using the file conform to the restrictions for programs using shared
resources.
Note that files using shared resources cannot be loaded
online.
The default options for cataloging a VSAM DDN (file) include LSR, which assumes use of shared resources. If you do not wish shared resources with other VSAM files, specify MACRF=NSR.
There are a few restrictions on Com-plete's support of VSAM: neither the locate option (OPTCD=LOC in the RPL), nor ISAM emulation (for example, the use of a VSAM cluster trough ISAM) are supported.
If you select the function FM from the UUTIL menu, the File Catalog Maintenance menu listing the various utility subfunctions is displayed on your screen:
15:40:01 TID 15 COM-5.1. User MBE 20.04.97
-- File Maintenance -- UFI0
Function ID Operands
--------------------------------- -- ------------------------------
File overview ................... FO Prefix/Name, System
Display catalog entry ........... DI Name, System
Catalog ......................... CA Name, System , Access method
Modify catalog entry ............ MO Name, System
Remove catalog entry............. RE Name, System
Set to BATCH status ............. BT Name
Set to ONLINE status ............ ON Name
Open (VSAM only) ................ OP Name
Close ........................... CL Name
SHOWCB ACB info (VSAM only) ..... SH Name
Select function .......
Operand ...............
System ................
Access method ......... ( VS / DA / IS )
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
End |
Meaning of the input fields:
| Select function | Type in a subfunction from the list under the heading ID. |
| Operand | Type in a DD/DLBL name (optional for subfunction FO). |
| System | Default: Global. |
| If you are not sharing COMSYS data sets among multiple Com-pletes, the easiest way is to use this default all the time. | |
| If you do share COMSYS data sets among
multiple Com-pletes, all files used from a certain Com-plete should be defined
as local objects for this Com-plete. Enter the patch character identifying the
appropriate Com-plete. Maintenance on the "local" file definitions should take
place only from the Com-plete they are assigned for, except when this Com-plete
is not active.
Notes:
|
|
| Access method | Specify the access method used if different from the current default, which is indicated by highlighting (for CATALOG function only). |
The File Overview function enables you to display the files cataloged to Com-plete. Use the operand field to specify a name or prefix as a starting point of the file list.
The following figure illustrates the display given by the File Overview function (result of function FO with operand *):
FC: D=Display M=Modify R=Remove S=SHOWCB B=BTCH O=ONLN P=OPEN C=CLOSE 10:03:06 TID 18 COM-5.1. User MBE 21.04.97 System: Global -- File Overview -- UFI1 FC DDName Type Status Attributes Users Last Access Note ------------------------------------------------------------------------------- . ADMF VSAM ONLN R U A closed . DFHTSD VSAM ONLN R U A closed . QAAUT VSAM ONLN R U A closed . QAAUTX VSAM ONLN R U A closed . QAAUTY VSAM ONLN R U A closed . QAFINC VSAM ONLN R U A closed . QAPER VSAM ONLN R U A closed . QAPERX VSAM ONLN R U A closed . QAPERY VSAM ONLN R U A closed . SKUVSAM VSAM ONLN R U A S closed Reposition to: END Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Refresh End Mode Forwd |
Meaning of the fields by column heading:
| Column | Description |
|---|---|
| FC | Input field to call a function for the appropriate file. Two of the functions available on the File Catalog Maintenance menu can be called by entering the appropriate function code in this field: |
| The first line of the screen lists valid function codes. You can enter function codes in more than one line. When you press , these function requests are satisfied successively. | |
| DDName | DD/DLBL-name of the file. |
| Type | Access method type of the file (VSAM, BDAM or ISAM). |
| Status | Indicates whether the file is currently in ONLINE or in BATCH status. |
| Attrib | Types of access allowed for this file in Com-plete: Retrieval (R), Update (U), Add (A), as well as additional options: Capture (C) and Serialization (S). |
| Users | For a VSAM file currently open: The number of ACBs in user programs currently open for this file. |
| Last access | For files currently opened in Com-plete: date and time of last access. Files not currently opened in this Com-plete are marked "closed". If you are dealing with "local" file definitions assigned to a different Com-plete (see main menu parameter System), this field containes the string "other system" indicating that no information is available from this Com-plete. |
| Note | Shows the result after a subfunction call. |
You can scroll the catalog forward PF8 or restart the display from any file name by entering a name or prefix in the field prompted Reposition to. You can switch the mode (press ) to display data set names and disposition (z/OS) or user catalog name (z/VSE):
FC: D=Display M=Modify R=Remove S=SHOWCB B=BTCH O=ONLN P=OPEN C=CLOSE 10:27:25 TID 18 COM-5.1. User MBE 21.04.97 System: Global -- File Overview -- UFI1 FC DDName T Data Set Name DISP Note ------------------------------------------------------------------------------- . ADMF V . DFHTSD V . QAAUT V SKU.SYSF.AUTO SHR . QAAUTX V SKU.SYSF.AUTOX.AIX SHR . QAAUTY V SKU.SYSF.AUTOY.AIX SHR . QAFINC V SKU.SYSF.FINANC SHR . QAPER V SKU.SYSF.PERSON SHR . QAPERX V SKU.SYSF.PERSX.AIX SHR . QAPERY V SKU.SYSF.PERSY.AIX SHR . SKUVSAM V SKU.TEST.VSAM SHR Reposition to: END Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Refresh End Mode Forwd |
This function enables you to display all attribute information cataloged for a file.
When the Display Catalog Entry function is invoked from the File Catalog Maintenance Menu, the DD/DLBL name must be specified in theoperandfield. Alternatively, you can use the line command D from a list of catalog entries (see the File Overview section).
The display of catalog entry information is the same as for the CATALOG function. The difference is that the DISPLAY function is "read" only (no modification possible). For a description of the information fields, see the section Catalog a File Entry below.
The CATALOG function enables you to add entries to the Com-plete file catalog. This function is not available from the File Overview menu. The DD/DLBL name to be cataloged must be specified in the operand field of the File Catalog Maintenance menu.
One of the valid access methods shown on the File Catalog Maintenance menu is always highlighted, indicating the current default. You can overwrite the default by specifying the required value in the Access Method field (z/OS only).
The access method dependent map is displayed, in which you can specify the file parameters to be included in the catalog entry. All parameters on the map are initialized with default values. Every time a DDN is cataloged, displayed, or removed, its values are saved and taken as current default for the corresponding access method. This information is lost when the UUTIL FM function is terminated.
After specifying the parameters, press to run a check for any invalid values or PF5 to check and save. In the latter case, if no errors are found, the entry is added to the Com-plete file catalog and control is returned to the File Maintenance menu. If an error is detected, an error message is displayed and the invalid value is indicated by the cursor position. Correct the value and press again.
A description of the access method dependent cataloging screen follows below.
The following map is displayed when cataloging a VSAM file:
14:23:37 TID 11 COMTEST User SAG 19.05.10
-- File Catalog Information -- UFI3
System: Global
DDName= SAGTEST VSAM
-------------------------------------------------------------------------------
DSName:.... SAG.VSAM.FILE
DISP:...... SHR (OLD/SHR) MACRF=
Password:.. (if protected) KEY , , (KEY,ADR,CNV)
Retrieval:. N (Y/N) , , DIR (SEQ,SKP,DIR)
Update:.... Y (Y/N) , OUT (IN ,OUT)
Add:....... Y (Y/N) NUB (NUB/UBF)
Capture:... N (Y/N) NRM (NRM/AIX)
Serialize:. Y (Y/N) NSR (NSR/LSR/RLS)
BUFSP= 0 Kbyte NDF (NDF/DFR)
BUFND= 0 NRS (NRS/RST)
BUFNI= 0 DSN (DDN/DSN)
STRNO= 0 NCI (NCI/ICI)
BSTRNO= 0 NIS (NIS/SIS)
SHRPOOL= 0 NFX (NFX/CFX)
RLSREAD= (NRI/CR/CRE/NORD)
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
End
|
Meaning of the parameters:
| Parameter | Description | ||||||
|---|---|---|---|---|---|---|---|
| DSName | Specifies the one-to-fourtyfour character data set name of the data set to be allocated to this DDN at OPEN time. | ||||||
| DISP | (z/OS only.) Specifies the disposition, OLD or SHR, to be used for data set allocation. | ||||||
| UCAT | (z/VSE only.) Specifies the one-to-seven character file name of the appropriate VSAM user catalog. | ||||||
| Password | For password protected VSAM clusters only. Specifies the password to be used by Com-plete when an OPEN for the VSAM cluster is issued, and that is required of each application program requesting access to the file. | ||||||
| Retrieval |
|
||||||
| Update |
|
||||||
| Add |
|
||||||
| Note: At least one of the access types retrieval, update or add must be allowed. | |||||||
| Capture |
|
||||||
| Serialize |
|
||||||
| Y must be specified for files used by Natural applications, but not for CMEDIT. | |||||||
| Com-plete uses an internal resource with compare-and-swap logic where applicaple to allow only one output-type request at any one time to be active against this file. For example, a GET-for-update request causes any requests issued by other users against the same file to wait until the first request is completed by an appropriate PUT, ERASE, or ENDREQ. Multiple read-only requests can run in parallel with each other, but will be serialized with output-type requests. Applications issuing terminal I/O functions while having uncompleted VSAM request(s) active are cancelled with a thread dump being produced. Setting this option avoids requests from failing due to the "buffer / controlinterval in use" condition (VSAM reason code X'14'). On the other hand, it requires all application programs accessing the file to observe certain rules to avoid running into deadlocks (A holds file X and waits for file Y, B holds Y and waits for X) or being cancelled when issuing terminal I/O. | |||||||
The following are the ACB parameters to be used for the central ACB Com-plete builds for the given DD/DLBL name. Note that Com-plete uses this one ACB to pass to VSAM all requests issued from any application program against any ACB with the same DD/DLBL name. Careful choice of all parameter values is recommended, taking into account the maximum possible number of users simultaneously accessing the file. For more detailed information about these parameters, their impact on resource usage and performance, and about VSAM tuning, please refer to the description of the ACB macro instruction in theVSAM Macro Instruction Reference and to the VSAM Administration Guide.
| Parameter | Description |
|---|---|
| BUFSP | Specifies the maximum amount of virtual storage in Kbytes to be used for data and index I/O buffers. |
| BUFND | Specifies the number of I/O buffers VSAM is to use for transmitting data. |
| BUFNI | Specifies the number of I/O buffers VSAM is to use for transmitting the contents of index entries. |
| STRNO | Specifies the maximum number of simultaneous positioning requests that will be made from all terminals for this VSAM cluster. |
| BSTRNO | Specifies the initial number of strings to be allocated for this VSAM cluster when it is first opened. |
| SHRPOOL | For future use. Specifies the number of the local shared resource pool to be connected to the ACB. With the current version of Com-plete, only SHRPOOL 0 is supported. |
| MACRF | Specifies the processing options to be used with the file. The specified values must include all options used by any program accessing the file. The IN and OUT options cannot be specified explicitly; they are defined by the retrieval/update/add parameters. Note that there are groups of options, which can be specified in any combination (shown on the map separated by commas) and groups of alternative options (separated by a slash '/') where only one option of each group can be specified. |
Note that the RMODE31 parameter cannot be specified, as it has no influence on application program processing. Com-plete forces RMODE31=ALL where applicable, thus causing buffers and internal VSAM control blocks to reside above the line.
The following map is displayed when cataloging an ISAM file.
14:28:48 TID 11 COMTEST User SAG 19.05.10
-- File Catalog Information -- UFI4
System: Global
DDName= ISAMFIL ISAM
-------------------------------------------------------------------------------
DSName:...... SAG.ISAM.FILE
VOLSER:...... (if not cataloged)
DISP:........ SHR (OLD/SHR)
Retrieval:... N (Y/N)
Update:...... Y (Y/N)
Add:......... Y (Y/N)
Capture:..... N (Y/N)
Note: Refer to the System Programmers Manual for restrictions on adding records
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
End Cat
|
Meaning of the parameters:
| Parameter | Description | ||||||
|---|---|---|---|---|---|---|---|
| DSName | Specifies the one-to-fourtyfour character data set name of the data set to be allocated to this DDN at OPEN time. | ||||||
| VOLSER | Specifies the six-character serial number of the volume containing this data set. Should be specified only if the data set is not cataloged. | ||||||
| DISP | Specifies the disposition, OLD or SHR, to be used for data set allocation. | ||||||
| Retrieval |
|
||||||
| Update |
|
||||||
| Add |
|
||||||
| Note: At least one of the access types retrieval, update or add must be allowed. | |||||||
| Capture |
|
||||||
The following map is displayed when cataloging an BDAM file.
15:14:55 TID 6 COM-5.1. User MBE 21.04.97
-- File Catalog Information -- UFI5
System: Global
DDName= MBETEST BDAM
-------------------------------------------------------------------------------
DSName:......
VOLSER:...... (if not cataloged)
DISP:........ (OLD/SHR)
OPTCD:....... (R/A)
RECFM:....... (F/FB)
Retrieval:... (Y/N)
Update:...... (Y/N)
Add:......... (Y/N)
Capture:..... (Y/N)
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
End Cat |
Meaning of the parameters:
| Parameter | Description | ||||||
|---|---|---|---|---|---|---|---|
| DSName | Specifies the one-to-fourtyfour character data set name of the data set to be allocated to this DDN at OPEN time. | ||||||
| VOLSER | Specifies the six-character serial number of the volume containing this data set. Should be specified only if the data set is not cataloged. | ||||||
| DISP | Specifies the disposition, OLD or SHR, to be used for data set allocation. | ||||||
| OPTCD | Specifies the value, R or A, to be used for DCB parameter OPTCD. | ||||||
| RECFM | Specifies the value, F or FB, to be used for DCB parameter RECFM. See the BDAM considerations above in this section. | ||||||
| Retrieval |
|
||||||
| Update |
|
||||||
| Add |
|
||||||
| Note: At least one of the access types retrieval, update or add must be allowed. | |||||||
| Capture |
|
||||||
The MODIFY function enables you to change any parameters of a file definition.
You are not recommended to modify parameters of a file while it is open online. Once you have changed the catalog entry, no more information is available about the parameter values currently in effect for the open file. Therefore, you are given a warning notification each time you use this function against an open file. See also the notes above concerning "global" and "local" definitions if you share COMSYS data sets among multiple Com-pletes.
Contents of the catalog entry are displayed in the same format as for the CATALOG function (see above). Press to confirm your changes or to cancel the request.
The REMOVE function enables you to delete an entry from the Com-plete file catalog.
Contents of the catalog entry are displayed in the same format as for the CATALOG function (see above). Press to confirm removal or to cancel the request.
This function allows you to disable online access to application files allocated to Com-plete.
If the file is currently opened by Com-plete, it is now closed and deallocated. Unlike the CLOSE function described below, the BATCH function sets a flag causing subsequent OPEN requests issued against this file from application programs to be rejected until it is set back to ONLINE status. Batch jobs accessing the data set are free to use the required DISP parameter (SHR or OLD).
To ensure that the file is currently not in online use, use the FO function (File Overview) described above. This function tells you whether the file is currently open, the current number of users and the time of the last access.
This function enables you to allow online access to application files which are set to BATCH status.
The ONLINE function does not allocate the data set to Com-plete, and no availability check is performed.
You can use the OPEN function described below to check if the data set is available for online processing.
The OPEN function enables you to open VSAM files.
Note:
Opening a file using this function does not release application
programs from opening the file.
You can use this function for test purposes, for example, to ensure you have specified a valid combination of ACB parameters using the Catalog or Modify functions, or to ensure the data set is available for online processing. If the OPEN failes, the appropriate reason code is displayed.
In most cases when an OPEN request fails, additional information
is available on the operator console.
The CLOSE function enables you to close and deallocate files currently opened in Com-plete.
A file is allocated to Com-plete and opened when it is first accessed by a Com-plete program and remains open until Com-plete is terminated. Consequently, storage used for I/O buffers and control blocks is not freed as long as Com-plete is active. This may lead to a high requirement of virtual storage, especially when VSAM files do not use shared resources.
In contrast to a CLOSE macro instruction used in an application program, the CLOSE function of this utility really closes the file, frees all storage reserved for I/O buffers and control blocks, and deallocates the data set from Com-plete.
The CLOSE function may also be useful when you want to change file parameters in the Com-plete file catalog and the file is currently open.
To ensure that the file is currently not in online use, use the FO function (File Overview) described above. This function tells you whether the file is currently open, the current number of users and the time of the last access.
When a VSAM data set is currently opened by Com-plete, information from its Access Control Block (ACB) can be displayed using the SHOWCB Information function.
The following figure illustrates an example display given by the SHOWCB Information function (the fields speak for themselves):
16:41:23 TID 6 COM-5.1. User MBE 21.04.97
-- VSAM SHOWCB Information -- UFI2
ACB= QAAUT RMODE31=ALL KSDS DATA INDEX
-------------------------------------------------------------------------------
Available space (in K) ............... 32 32
Number of extents .................... 1 1
Number of index levels ............... 1
Control interval size ................ 8192 8192
(Max) Record length .................. 800 8185
Key length and offset in record ...... 8 0
Total records at OPEN time ........... 40 1
Total records now .................... 40 1
Since OPEN: Records retrieved ........ 0
Records updated .......... 0 0
Records deleted .......... 0
EXCP count ............... 0 0
I/O buffers requested ................ LSR
I/O buffers allocated ................
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
Refresh End |
For more information about the values returned by the SHOWCB macro instruction, please refer to the description of the SHOWCB macro instruction in the VSAM Macro Instruction Reference documentation.