The M$CLOSE service terminates and inhibits I/O through a specified DCB, unti I the DCB is again opened. In addition, unique positioning and updating operations occur for the fol lowing devices and fi les.
For tape updating, the M$CLOSE service performs these additional functions:
o Performs end-of-file processing appropriate to tapes:
For free or managed tape, if the last operation performed was a write, two fi Ie marks are written and the tape positioned between them. If the last operation was a write-end-of-fi Ie, one fi Ie mark is written and the tape positioned before it.
For labeled tape User Trai I ing Labels may be specified to be written fol lowing the End Of Fi Ie label group for CREATEd fi les. A buffer may be specified for receipt of any UTLs present for IN or UPDATE fi Ie if the file was not modified. Tape position
is left fol lowing the file mark which fol lows the end of fi Ie label group (including UTLs).
o Positions the tape fol lowing end-of-fi Ie processing, if the POS parameter is specified.
For disk the M$CLOSE service performs these additional functions:
o Handles fi Ie disposition, which may include releasing a fi Ie or entering it in the account fi Ie directory. The disposition of a fi Ie is determined in part by
parameters specified when the DCB was opened. If a fi Ie was opened with
DISP-SCRATCH for any function, the close process always releases the secondary storage al located to the file. If a fi Ie was opened with DISP=NAMED, the close process disposes of the fi Ie as specified by the user in the DISP parameter of the M$CLOSE service.
o Permits the user to modify fi Ie attributes (see CHGATTR).
o Permits the user to release unused granules (see RELG).
o AI lows the user to request rebuilding of the upper level index for a keyed, indexed or IREL fi Ie (see REBLO).
The form of the call for this service is as follows:
CALL M$CLOSE (FPT_CLOSE) [ALTRET (label)];
The parameters for the service are as fol lows:
ACCESS - VARIABLE Locates an access control list area (see the VLP_ACCESS macro
described in this section). If CHGATT-YES and the user has the required permission, the specified list becomes the new access control list for the file.
3-42 M$CLOSE - Close DCB CE74-00
ACCT
=
VARIABLE Locates an area containing an account name (see the VLP_ACCT macro which is described later in this section). If CHGATT-YES and the user has the requiredpermission, the specified account becomes the new account in which the file resides, provided the account already exists on the same packset as the old account. This facility is not yet implemented.
ACSVEH - VARIABLE Locates an access vehicle control list (see the VLP_ASCVEH macro described in this section). If CHGATT.YES and the user has the required permission, the specified list becomes the new access vehicle control list for the file.
ALTBLD - fYESINOI YES specifies that the alternate indices for this indexed or IREL file are to be rebui It. NO specifies that they are not to be rebuilt. The default is to rebui Id them only if necessary.
In order to update the alternate indices on the close, the monitor initiates a load and link to ALTKEY_MDN.:SYS. This processor uses X$SORT to sort the alternate indices into their proper order. The new keys are then written to the file. If any errors are detected during the process, an error is returned to the user. Under some
circumstances, errors may be written directly to the user through the M$OO DCB.
ALTKEYS - VARIABLE Locates a VLP_ALTKEYS which describes the alternate indices to replace the existing alternate indices in the indexed file, if CHGATT-YES, and the user has the required permission. The alternate keys may only be redefined if the last key
in the new definition does not extend beyond the last key in the old definition. The default causes this parameter to be ignored.
BUPM - fYESINOI Specifies a change in BUPM if CHGATT is YES. See DESC.BUPM in M$OCB.
CHGATT - IYESINOI YES requests modification of one or more of the fol lowing fi Ie attributes: BUPM, TYPE, XTNSIZE, EXPIRE, LSLIDE, LRDL0, SPARE, NAME, PASS, ACCESS, ASCVEH, UATTR, I NSTATTR, PROCATTR, ALTKEYS, and IRKEYS. The modifications are permitted
if the file has been opened specifying FUN-UPDATE, or FUN=CREATE, and the user has REATTR permission, except for NAME. PASS, ACCESS and ACSVEH. which require DELF permission.
DCB - DCBNAME Specifies the DCB to be closed.
DISP· ISAVEIRELEASEI Applies to disk and tape files created with DISP-NAMED. On a close, DISP specifies whether the NAMED fi Ie is to be saved or released. (At open the DISP parameter specifies NAMED if the user intends to retain the file and SCRATCH if the user does not intend to retain the file. Any fi Ie opened with SCRATCH disposition is always released at close. Thus the DISP parameter on the close is not meaningful for scratch files.)
When DISP-SAVE the file is cataloged if it is not already represented in the file directory. If the fi Ie replaces an existing file (the fi Ie was opened with CTG-NO and EXIST-NEWFILE). the new file replaces the old file which is deleted from the file directory. The old file is released when al I current file users close the associated OCBs.
When DISP-RELEASE, the file is deleted from the fi Ie directory (if it was previously cataloged). The file is released when all current file users close the associated OCBs.
The default is SAVE for cataloged fi les and RELEASE for uncataloged files. (Any file declared as a SCRATCH file is always released.)
EXPIRE - IdddlNEVERI Specifies a change in EXPIRE if CHGATT is YES. See EXPIRE in M$OPEN.
GHSTACS
=
VALUE-DEC{0-15). Specifies a change in GHSTACS if nonzero and CHGATT is yes.See GHSTACS in M$OPEN. The value NONE specifies that GHSTACS is to be reset. If specified for a COMGROUP. the change does not have any effect until the COMGROUP is reinitial ized (opened with no current users).
CE74-00 M$CLOSE - Close DCB 3-43
IFPARAM = VARIABLE Locates an area containing FIT data which may be used in conjunction with CHGATT=YES to alter various portions of a file's FIT (see CHGATT for a list of the
01 terob I e ones),
INSTATTR - VARIABLE Locates an area containing installation attributes (see the VLP_ATTR macro described in this section). If CHGATT=YES and the user has the required
permission. the specified instal lotion attributes become the new insta!!ation attributes for the f i Ie.
IRKEYS
=
VARIABLE Locates a VLP_IRKEYS which describes the alternate indices to replace the current definitions. if CHGATT=YES. and the user has the required permission. The user may redefine the keys only under special circumstances. First of all. the primary key in the new definition must match the existing primary key definition. Also. the last key in the new definition must not extend beyond the last key in the current definition. This can only be used for IREL files.LRDL0 - VALUE-DEC(1-511). Specifies a change in LRDL0 if CHGATT is YES. See LRDL0 in MSOPEN.
LSLIOE = VALUE-OEC(1-511). Specifies a change in LSLIDE if CHGATT is YES. See LSLIDE in MSOPEN.
NAME - VARIABLE Locates an area containing a fi Ie name (see the VLP_NAME macro described later in this section). If CHGATT=YES and the user has the required permission. the specified name becomes the new name for the file.
NOMARKS = IYESINOI For free tapes only. YES specifies that file marks are not to be written on a free tape when it is closed after having been modified. Normally. two file marks are written to indicate end of tape. YES specifies if tape is not to be
positioned after the next file mark when it is closed after not having been modified.
Normally. the tape is positioned to the beginning of the next free tape file. The default is NO.
PASS
=
VARIABLE Locates an area containing a password (see the VLP_PASS macro which is described later in this section). If CHGATT-YES and the user has the requiredpermission. the specified password becomes the new password for the file.
POS - OPTION Specifies positioning for magnetic tape. IF POS is not specified. the default close positioning is retained with one exception. If DISP-RELEASE is specified for a CREATEd TAPE fi Ie. POS is assumed to be PTL.
PTL: For labeled tapes. the volume (set) is positioned before the Header label group preceding the fi Ie just closed. For free tapes. the volume is left after the fi Ie mark preceding the data section just closed. A device data section includes the file mark
immediately fol lowing.
PTV: For labeled. managed. and free tapes. the tape is rewound.
REM: For labeled. managed. and free tapes. the current volume is unloaded. If the volume and drive were reserved with a RESOURCE command. the drive remains allocated to the user.
REL: For labeled. managed. and free tapes. the current volume is unloaded and the drive is released to the system.
The default for labeled tapes is to position following the file mark fol lowing the EOF label group. The default for free and managed tapes is to leave position unchanged unless the file was modified in which case two file marks are written and tape left positioned between them.
PROCATTR - VARIABLE Locates an area containing processor attributes (see the VLP_ATTR macro described in this section). If CHGATT-YES and the user has the required
permission. the specified processor attributes become the new processor attributes for the f i Ie.
W$CLOSE - Close DCB CE74-00
REBLD - IYESINOI YES requests rebuilding of the upper level index for a keyed, indexed or IREL disk file.
(Re)bui Iding an upper-level index structure increases the number of granules in the fi Ie, but has no effect upon the actual content of the level-0 index granules. REBLD (re)creates a pyramid structure which File Management can use to locate keys in the level-0 granules without having to search through the level-0 granules in a sequential fashion.
A level-1 structure should not exist if there are 3 or fewer granules at level 0. At an attempt to read a record whose key is not located in whichever level-0 granule is
currently in memory (when there is an upper-level index structure), then Fi Ie Management goes directly to the first granule at the highest level, and searches "downward" toward
level-0 to locate the key. If there are 1, 2, or 3 granules located at level 0, then this multi-level search requires (on the average) more disk accesses than would a sequential search at level-0 (which occurs if there is no upper-level index). Creating 4 granules of level-0 index is a "break-even" point at which a multi-level search
requires (on the average) just as many reads as a sequential search. File Management wi I I therefore create a level-1 index when the DCB is closed. For files with 5 or more granules of level-0 index, the multi-level index pyramid can save a significant number of disk I/Os.
Instead of using the REBLD option whenever creating (or updating) a keyed file, it is advisable to have File Management (re)bui Id the index pyramid whenever there would be a significant benefit from doing so. Fi Ie Management normally rebui Ids the pyramid whenever there are at least 3 adjacent level-0 index granules which cannot be reached from level-1, or when there are at least 510 level-0 granules anywhere in the fi Ie which can't be reached. For a file that is read and updated frequently, and not opened and closed often, then it might be advisable to change these figures. The former (3) can be changed by specifying LRDLO=n, and the latter can be changed by specifying LSLIDE-n. A value of LSLIDE-1 wi I I cause the upper-level pyramid to be rebuilt at M$CLOSE time, if a new level-0 granule has been added anywhere in the fi Ie. This wi I I guarantee a
high-quality pyramid but incurs the overhead involved in the frequent rebuilding of the pyramid at fi Ie-closure time.
RELG = IYESINOI YES requests release of unused granules allocated for this disk file.
RELG=YES is typically specified when the user anticipates I ittle or no updating to a
f i Ie.
SN - VARIABLE Locates a VLP_SN area. This area wil I contain the tape serial numbers which were used to create new tope volumes from scratch topes.
described later in this section for a definition of serial number list.
SPARE - VALUE-DEC(1-511). Specifies a change in SPARE if CHGATT is YES. See SPARE in M$OPEN.
TYPE - VALUE-CHAR(2) is the processor-supplied file type. If CHGATT-YES and the user has the required permission, the type code becomes the new type code for the file. See M$OPEN for a I ist of the file type codes.
UATTR = VARIABLE Locates an area containing user attributes (see the VLP_ATTR macro described in this section). If CHGATT-YES and the user has the required permission, the specified user attributes become the new user attributes for the file.
UTL - VARIABLE Locates a VLP_ULBL area for User Trailer Labels (UTLs). UTLs are read into the buffer at close of the file if the file was opened with FUN-IN or UPDATE if the fi Ie was not modified. UTLs are written from this buffer during the close of a file opened with FUN=CREATE. User labels are 80 bytes each and must begin with 'UTL'. Labels are pocked into the buffer contiguously.
XTNSIZE - VALUE-DEC(l-?). Specifies a change in XTNSIZE if CHGATT is YES. See XTNSIZE in M$OPEN.
A listing of additional fields in the V area follows. These fields are not set via parameters for M$CLOSE.
M$CLOSE - Close DCB 3-45
EfTOPER.ASTOW# is used by EFT to indicate that the fi Ie close should take the contents of the 0'th entry of the VLP_SN area described by FPT.SN_ along with the fi Ie open time and merge them into the area of the fi Ie FIT described by the %COOE06 structure.
EFTOPER.BACKUP# is used by EFT to indicate that the fi Ie close should take the contents of the 0'th entry of the VLP_SN area described by the FPT.SN_ along with the file open time and merge them into the area of the fi Ie FIT described by the ~COOE05 structure.
See Appendix C of CE75.
EfTOPER.OELFOE# is used by EFT to indicate that the file directory entry describing the fi Ie should be removed, compacting the directory, and removing al I knowledge of the f i Ie.
EfTOPER.ISTOW# is used by EFT to indicate that the fi Ie close should result in the granules being released, and a special directory entry created that may later be accessed through an M$OPEN that asks for FPARAM data. The ~COOE06 macro may then be used to determine which tape the fi Ie resides upon. See Appendix C of CE75. ISTOW and ASTOW must both be used if the fi Ie is being stowed inactive the first time.
EfTOPER.UPDDESC# is used by EFT to indicate that the fi Ie close should move the descriptor bits from the FPT into the appropriate areas of the fi Ie FIT and the fi Ie directory.
The VLP_VIRTUAL macro describes the parameters for a large virtual segment when a keyed fi Ie is being opened. It contains parameters that influence the use of a large virtual segment.
INITIALIZE - IYESINOI. YES specifies that any page that has not been accessed before, and does not exist in the paging file, wil I be initial ized to the value specified in INITVALUE. NO specifies that initialization wi I I not be done; the contents of the page is unchanged. The default is NO.
INITVALUE - VALUE-DEC(0-?). Value wi I I be used when INITIALIZE=YES is specified as the value that the page is to be set to on the initial access of the page (if it does not exist in the paging file). The default is 0.
MINPHYS=VALUE-DEC(1-2048). Specifies the minimum number of physical pages backing the virtual area. This parameter determines the least number of pages that are held within memory at any given time. The parameter has a great effect on the access speed of the virtual segment. The default is ten pages.
NOFILE = IYESINOJ. Specifies if the user wants control of the missing page faults or not. If YES is specified, whenever a page needs to be paged in, the user wil I get an event. The user then can use M$CVM or M$GVP to al locate that page.
PHYSICAL=VALUE-DEC(1-2048). Specifies the number of physical pages backing the virtual area. This parameter determines how many pages are held within memory at any given time.
The parameter has a great effect on the access speed of the virtual segment. The default is ten pages.
PTR$=POINTER. is returned on successful open with a pointer to the segment that was used for this large virtual area. It should be used on all references to the area.
SCALE - VALUE-DEC(0-63) See VLP_RECFIELD for more information.
SEGNUM - VALUE. Specifies which of the three large virtual segments is to be used for this file. The values are VS1, VS2, and VS3.
SEGSIZE - VALUE-DEC(1-2097152) specifies in words the size of the large virtual segment.
The actual bounding of a virtual segment is done on a page basis so the SEGSIZE will be rounded up to a number of virtual pages. Any page access that is not within bounds wil I cause a Missing page fault.
CE74-00
WSQ - This number is returned to the user containing the WSQ allocated. This is needed in conjunction with the NOFIlE option to determine what WSQ to use.