DMSCLBLK - Close Blocks

Read syntax diagramSkip visual syntax diagram DMSCLBLK , retcode , reascode , token , COMMITNOCOMMIT SHORTDATEFULLDATEISODATE , length1 ,date,time,fm_noGroup 1
Group 1
Read syntax diagramSkip visual syntax diagram , recform ,lrecl,num_recsGroup 2
Group 2
Read syntax diagramSkip visual syntax diagram , max_blk_no ,ptr_blk_levelGroup 3
Group 3
Read syntax diagramSkip visual syntax diagram , top_blk_no ,data_blks_usedGroup 4
Group 4
Read syntax diagramSkip visual syntax diagram , wuerror , length2 ,0,requestid

Context

File Pool Administration

Call Format

The format for calling a CSL routine is language dependent. DMSCLBLK is called only through DMSCSL. The routine name is the first parameter in DMSCSL’s parameter list:

DMSCLBLK
(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 DMSCLBLK routine to end processing of a file that was opened previously using the DMSOPBLK (Open Blocks) routine.

Parameters

retcode
(output, INT, 4) is a variable for the return code from DMSCLBLK.
reascode
(output, INT, 4) is a variable for the reason code from DMSCLBLK.
token
(input, CHAR, 8) is a variable returned to the caller on Open Blocks (DMSOPBLK).
COMMIT
(input, CHAR, 6) means keep all changes associated with the work unit. That is, all changes made during a work unit, from either the start of the work unit or from the last COMMIT, are kept.
NOCOMMIT
(input, CHAR, 8) means do not keep the changes.
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 signed variable containing the length of the preceding character parameter (COMMIT or NOCOMMIT, and SHORTDATE, FULLDATE, or ISODATE, if specified). See Compound Variables for details on coding compound variables.
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 to specify 4-digit years.

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. This is a variable 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. If you omit this field or set it to 8 blanks, the system determines the time.
If you specify a time, a colon (:) must be used as the separator character and 2 digits must be specified in each position. For example:
12:01:09
fm_no
(input, CHAR, 1) is a variable for specifying the file mode number of the file you are closing.
recform
(input, CHAR, 1) is a variable for specifying whether the file being closed consists of fixed-length or variable-length records. Acceptable values are:
F
indicates that all the records in the file have the same length.
V
indicates that the records in the file may have different lengths.
lrecl
(input, INT, 4) is a variable for specifying the logical record length of the file being closed.
num_recs
(input, INT, 4) is a variable for specifying the number of records in the file.
max_blk_no
(input, INT, 4) is a variable for specifying the greatest block number for the file being closed.
ptr_blk_level
(input, INT, 4) is a variable for specifying the number of pointer block levels used in the file being closed.
top_blk_no
(input, INT, 4) is a variable for specifying the block number of the first block of the file being closed.
data_blks_used
(input, INT, 4) is a variable for specifying the number of data blocks used in the file being closed.
wuerror
(output, CHAR, length2) is a variable containing the information necessary to have CMS return extended error information. If it is specified, it must be followed by a length field.
length2
(input, INT, 4) is a signed 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 synchronous. If it contains a binary 1 on input, the request is asynchronous and CMS generates an integer to identify the asynchronous request. This integer is placed in requestid, which is passed on a later Check request. If, on return, the requestid is still 1, no server call was needed. It will not be necessary to call DMSCHECK because the function has already been completed.

Usage Notes

  1. If the Open Blocks intent was for:
    • NEW, WRITE, REPLACE, or CREATEMIG of an SFS file
    • REPLACE of a BFS file
    the values of the parameters listed below must match the values for the file being closed.

    The values of these parameters are returned by DMSOPBLK when the intent is for READ, NEW, WRITE, REPLACE, or CREATEMIG. If you change the file, you have to update the parameters before you close the file.

    If the Open Blocks intent was for REPLACE of a BFS file, all of the following parameters must be specified with the indicated values:
    Parameter
    Required Value
    fm_no
    1
    recform
    F
    lrecl
    1
    num_recs
    The number of bytes in the file
    max_blk_no
    data_blks_used + ptr_blk_level
    ptr_blk_level
    The number of generated pointer block levels in the file
    data_blks_used
    The number of 4KB data blocks in the file
    top_blk_no
    data_blks_used + ptr_blk_level
  2. File mode 3 files are not erased after reading.
  3. The application is responsible for closing any files that it opened with Open Blocks (DMSOPBLK). CMS will roll back any work units that have unclosed files (opened by DMSOPBLK) at normal end and abnormal end-of-command.
  4. If a file or directory is open on a work unit and COMMIT is specified, the file or directory remains open and all changes are committed. A rollback does not occur.
  5. The date and time attributes are updated only when the file has been created or changed:
    • 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 the DMSOPBLK routine, DMSOPBLK - Open Blocks).

    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.

  6. Opened files that have been modified through DMSWRBLK prevent a commit. However, you can commit on the close of this file, when it is the only such file open.
  7. Catalogs may not be open at commit time as the result of an OPEN CATALOG request.
  8. If the COMMIT parameter is specified and the return code is 8, then either:
    • An error occurred during the processing of the Close Blocks 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 request 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.
  9. A request ID is returned if the request is to be asynchronous.
  10. A return code of 0 or 4 for an asynchronous request indicates only that the request was accepted for processing; processing errors can still occur. A return code of 0 or 4 for a synchronous request indicates that the operation was completed successfully.
  11. 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.
  12. 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.
  13. 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).
  14. 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.

  15. 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 DMSCLBLK, see Return Codes.

The following table lists the special reason codes returned by DMSCLBLK. WARNING means the request was processed and there were some exceptional conditions, or the desired state already exists. ERROR indicates that 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) routine for other possible codes.

DMSCLBLK 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 write was done for a new file created as a result of OPEN NEW or OPEN WRITE. Upon closing, the file no longer exists.
WARNING 10070 Open intent was REPLACE, but no write was issued. Original file is kept.
WARNING 10220 File mode other than 1 specified for a BFS file.
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 or rollback processing.
ERROR 10000 System error. Attempt to write a block but a file is not open for NEW, WRITE, or REPLACE.
ERROR 10100 System error. Conflicting file attributes. Number of blocks does not match MAXBLOCK or not all blocks have been written.
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 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 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. Applicable only when COMMIT parameter is specified.
ERROR 51100 System error. No minidisks assigned to the storage group. Applicable only when COMMIT parameter is specified.
ERROR 65400 Request cannot be performed on a BFS object due to one or more of the following:
  • lrecl value other than 1 specified
  • recform value other than F specified
ERROR 76000 System error in file pool server commit function. The current unit of work has been rolled back. Applicable only when COMMIT parameter is specified.
ERROR 90129 There are already 231-1 blocks in a file to which you have written in the same work unit, therefore a new logical block is not available. Applicable only when COMMIT parameter is specified.
ERROR 90310 Incorrect option in CSL parameter list. Valid parameters are COMMIT or NOCOMMIT, and SHORTDATE, FULLDATE, or ISODATE.
ERROR 90320 Conflicting options in CSL parameter list.
ERROR 90330 Duplicate options in CSL parameter list.
ERROR 90415 Incorrect length specified for the wuerror parameter. A nonzero length must be at least 12 bytes.
ERROR 90472 Incorrect requestid specified, must be 0 or 1.
ERROR 90482 Attributes parameter was not specified for a file opened with intent of NEW, WRITE, or REPLACE.
ERROR 90492 Valid parameter must be COMMIT or NOCOMMIT
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 Incorrect time format; must be in the form hh:mm:ss.
ERROR 90499 Nonnumeric value in time specification.
ERROR 95600 You have another file pool object open and specified COMMIT.
ERROR 95700 System error. No open file pool object found for the specified token.
ERROR 96500 COMMIT was specified, and there is an asynchronous request in process for the specified work unit.