DMSCLOSE - Close
Context
File System Management: SFS, BFS, and minidisk
Call Format
The format for calling a CSL routine is language dependent. DMSCLOSE is called only through DMSCSL. The routine name is the first parameter in DMSCSL’s parameter list:
- DMSCLOSE
- (input, CHAR, 8) can be passed as a literal or in a variable.
For more information and examples of the call formats, see Calling VMLIB CSL Routines.
Purpose
Use the DMSCLOSE routine to end processing of a file previously opened using the DMSOPEN (Open) routine.
Parameters
- retcode
- (output, INT, 4) is a variable for the return code from DMSCLOSE.
- reascode
- (output, INT, 4) is a variable for the reason code from DMSCLOSE.
- token
- (input, CHAR, 8) is a variable for uniquely identifying the file to be closed. This token was returned to the caller by DMSOPEN.
- COMMIT
- (input, CHAR, 6) means keep all changes associated with the work unit (including changes made to other files), from either the start of the work unit or the last commit. See the COMMIT option description under Common Parameters for more information.
- NOCOMMIT
- (input, CHAR, 8) means do not keep the changes.
DMSCLOSE of a BFS file causes the updates in that file to be committed even if NOCOMMIT is specified. However, this does not affect other participating resources updated on the work unit, including SFS files.
- SHORTDATE
- (input, CHAR, 9) indicates the format of the date parameter is yy/mm/dd, where yy is the 2-digit year, mm is the month, and dd is the day of the month. SHORTDATE is the default.
- FULLDATE
- (input, CHAR, 8) indicates the format of the date parameter is yyyy/mm/dd, where yyyy is the 4-digit year, mm is the month, and dd is the day of the month.
- ISODATE
- (input, CHAR, 7) indicates the format of the date parameter is yyyy-mm-dd, where yyyy is the 4-digit year, mm is the month, and dd is the day of the month.
- length1
- (input, INT, 4) is a variable containing the length of the preceding character parameter (COMMIT, NOCOMMIT, SHORTDATE, FULLDATE, or ISODATE). See Compound Variables for coding details.
- date
- (input, CHAR, 8 or 10 ) is the date attribute that will be saved with the file. The date
attribute is the date that the file was last updated. It is a character variable with a length of 8
or 10 in the form yy/mm/dd, yyyy/mm/dd, or
yyyy-mm-dd, where yy is the 2-digit year,
yyyy is the 4-digit year, mm is the month, and
dd is the day of the month.
You must specify either the FULLDATE or the ISODATE parameter if you want to use a 4-digit year.
You can have the system determine the date by omitting the variable or by specifying 8 blanks for SHORTDATE, or 10 blanks for FULLDATE or ISODATE. If you do not specify the SHORTDATE, FULLDATE, or ISODATE parameter, and you omit the date variable, or leave blanks, the system generates the date. The value is in local time.
Use a slash (/) as the separator character to separate the year, month, and day, unless you have specified the ISODATE parameter, which requires a dash (–) separator. For example, the SHORTDATE format of 3 May 1996 is specified as:
the FULLDATE format is specified as:96/05/03
and the ISODATE format is specified as:1996/05/03
1996-05-03
- time
- (input, CHAR, 8) is the time attribute that will be saved with the file. The time attribute is the time at which the file was last updated. The contents of this variable must be specified in the form hh:mm:ss, where hh is the hour of the day in 24-hour notation, mm is the minutes, and ss is the seconds. To use the system-determined time, either omit this parameter or specify eight blanks.
- wuerror
- (output, CHAR, length2) is a variable used to specify an area for returning extended error information. If it is specified, it must be followed by a length field. For more information, see wuerror under Common Parameters.
- length2
- (input, INT, 4) is a variable containing the length of the preceding character parameter (wuerror). Specifying 0 has the effect of omitting the wuerror parameter. To use the wuerror parameter, specify a length of 12 plus 136 bytes for each group of extended error information that may be passed back. Specifying a nonzero length less than 12 is incorrect and causes an error reason code to be returned.
- requestid
- (input/output, INT, 4) identifies a specific asynchronous request. If it is omitted or contains
a binary 0 on input, the request is to be synchronous. If it contains a binary 1 on input, then the
request is to be asynchronous and CMS generates an integer to identify the asynchronous request.
This integer is placed in requestid which is passed on a later Check
(DMSCHECK) request.
The processing of a given DMSCLOSE request may not require communication with the server. In this case, the operation is performed synchronously regardless of the value specified in requestid, and the value of requestid is not changed by the operation.
Usage Notes
- DMSCLOSE of a BFS file causes the BFS updates to be committed whether or not COMMIT is specified. This does not affect other participating resources updated on the work unit, including SFS files. Changes made to BFS files are not protected. That is, they do not participate in CRR and are committed independently of other resources, including SFS, on the work unit.
- If the COMMIT parameter is specified and the return code is 8, then either:
- An error occurred during the processing of the Close operation, or
- The operation was completed but the work unit could not be committed. In this case the reason code is 50500. If the wuerror parameter was specified, a code for the specific reason that the attempt to commit failed is put in the error_reascode_info field in one of the FPERROR entries. See the Return Codes and Reason Codes for descriptions of these codes.
- An empty file is created if ALLOWEMPTY was coded on DMSOPEN and there are no records in the file at the time DMSCLOSE is issued. If a minidisk file was opened with an intent of REPLACE and no records were written, the file is erased. Empty files cannot be created on a minidisk.
- The date and time attributes are updated only when the file has been created or changed and:
- You wrote to the file successfully
- Or you are creating an empty SFS file or are replacing an SFS or BFS file with an empty file (see the ALLOWEMPTY parameter of DMSOPEN - Open).
If the file is a BFS file and the date provided is earlier than January 1, 1970, the time and date are set to 00:00:00 and January 1, 1970.
- When a minidisk file is closed, all updates to the file have been made. If COMMIT was specified, the work unit will be committed. If an error occurs during the attempt to commit the work unit, the operations associated with that work unit will remain uncommitted but the minidisk file will be closed (the file is updated).
- For an asynchronous request, the return code indicates only whether the request was accepted for processing (rc=0) or was immediately rejected; processing errors can still occur. In contrast, a return code of 0 for a synchronous request means the operation was completed successfully.
- If you have an active asynchronous request for a file pool, you cannot issue any other requests (except a rollback request) for the affected file pool on the specified work unit.
- Requests for minidisks are always processed synchronously and requestid is returned unchanged.
- Only one of the three date format parameters (SHORTDATE, FULLDATE, or ISODATE) can be specified. SHORTDATE is the default. The date format chosen applies to the date parameter.
- When date is specified with the FULLDATE or ISODATE parameters, the 4-digit year (yyyy) range is restricted to the range 1900-2099 (that is, the century portion of yyyy must be either 19 or 20).
- When date is specified with the SHORTDATE parameter, the sliding
window technique is used to calculate a 4-digit year (yyyy) from the
2-digit year that is input. The 4-digit year will then be associated with the file.
The calculation assumes the 2-digit year is within the 100 year window as calculated by:
(current_year - 50) = low end of windowFor example, if a 2-digit year of 05 is supplied, and the current year (current_year) is 1997, the window range is between the years 1947 and 2046. In this case, the calculation changes the 2-digit year of 05 to the 4-digit year 2005.
(current_year + 49) = high end of window - If you want to perform arithmetic or conversion operations on the time stamps that are input to this routine, you may find the DateTimeSubtract CSL routine helpful. See z/VM: CMS Application Multitasking.
Return Codes and Reason Codes
For lists of the possible return codes from DMSCLOSE, see Return Codes.
The following table lists the special reason codes returned by DMSCLOSE. WARNING means the request was processed, or the desired state already exists. ERROR means the request failed. Warnings cause return code 4, and errors cause return code 8 or 12.
DMSCLOSE can also return the common CSL reason codes, which are codes that can occur with most file system management and related routines. For a list of the common reason codes, see Common Reason Codes.
Severity | Reason Code | Description |
---|---|---|
WARNING | 10050 | No file has been created. The file was empty when you tried to CLOSE it, either
because:
|
WARNING | 10070 | The open intent was REPLACE and no write was issued. The original SFS file is kept, either because DMSOPEN was not specified with ALLOWEMPTY, or because the file pool server does not support empty files. |
WARNING | 51050 | File space warning threshold reached or exceeded. |
WARNING | 51060 | File space warning threshold reached or exceeded for one or more file spaces during commit processing. |
WARNING | 55777 | The ERASE function issued by DMSCLOSE for a file mode number 3 file failed. |
WARNING | 90617 | The minidisk file was erased because it was opened with an intent of REPLACE, but no records were written to it. |
ERROR | 10000 | System error. Attempt to write a block but the file is not open for NEW, WRITE, or REPLACE. |
ERROR | 10100 | System error. COMMIT was specified. Conflicting file attributes. |
ERROR | 20000 | Duplicate object found in file pool catalog. This error occurs only when the COMMIT option is specified: you have created a file pool object, and you or another user has concurrently created an object with the same name on another unit of work. The other unit of work was committed first, and your attempt to commit your unit of work has failed. |
ERROR | 50500 | The operation was successful but the work unit could not be committed. If the wuerror parameter was specified, a code for the specific reason that the attempt to commit failed is put in the error_reascode_info field in one of the FPERROR entries. See the Return Codes and Reason Codes for descriptions of these codes. |
ERROR | 50700 | There is no room in the file space to complete this request. |
ERROR | 51000 | Storage group space limit exceeded. |
ERROR | 51100 | System error. No minidisks assigned to the storage group. |
ERROR | 76000 | System error in file pool server commit function. The current unit of work has been rolled back. |
ERROR | 90129 | There are already 231 - 1 blocks in the file, therefore a new logical block is not available. |
ERROR | 90130 | There is not enough free virtual storage available for file system control blocks. |
ERROR | 90300 | Illegal parameter specified. The COMMIT or NOCOMMIT parameter was missing or specified incorrectly, or SHORTDATE, FULLDATE, or ISODATE was specified incorrectly, or extraneous parameters were found. |
ERROR | 90320 | Conflicting options in CSL parameter list. |
ERROR | 90330 | Duplicate options in CSL parameter list. |
ERROR | 90415 | Invalid length specified for the wuerror parameter. A nonzero wuerror length must be at least 12 bytes. |
ERROR | 90472 | Invalid requestid. It must be 0 or 1. |
ERROR | 90494 | Incorrect date format. The date must be specified in one of the following
formats:
|
ERROR | 90495 | Incorrect date specified for yyyy, century yy portion is restricted to 19 or 20. |
ERROR | 90496 | Nonnumeric value in date specification. |
ERROR | 90498 | Invalid time format; must be in the form hh:mm:ss. |
ERROR | 90499 | Nonnumeric value in time specification. |
ERROR | 95600 | The work unit was not committed. This could occur because an open file was modified with Write Blocks or a file in the directory is open and the file pool server does not have the Commit Without Close enhancement. |
ERROR | 95700 | System error. COMMIT was specified. No open file found for internal token passed to SFS. |
ERROR | 95750 | No file opened by DMSOPEN found for the specified token. |