DMSCLOSE - Close

Read syntax diagramSkip visual syntax diagram DMSCLOSE , retcode , reascode , token , COMMITNOCOMMIT SHORTDATEFULLDATEISODATE , length1 ,date,time,wuerror,length2,requestid

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:
96/05/03
the FULLDATE format is specified as:
1996/05/03
and the ISODATE format is specified as:
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

  1. 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.
  2. 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.
  3. 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.
  4. 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.

  5. 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).
  6. 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.
  7. 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.
  8. Requests for minidisks are always processed synchronously and requestid is returned unchanged.
  9. 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.
  10. 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).
  11. 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 window
    (current_year + 49) = high end of window
    For 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.

  12. 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.

Note: Other return and reason codes can be returned by this routine when the COMMIT parameter is specified. See the description of the DMSCOMM (Commit) CSL routine for other possible codes.

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:
  • OPEN NEW was specified and the file was not written to
  • Or because OPEN WRITE was specified for a file that did not exist and the file was not written to. An empty file was not created either because ALLOWEMPTY was not specified on the OPEN or because the file pool or minidisk does not support empty files.
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:
  • yy/mm/dd if SHORTDATE is specified
  • yyyy/mm/dd if FULLDATE is specified
  • yyyy-mm-dd if ISODATE is specified
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.