DMSGETDF - Get Directory - File
Context
File System Management: SFS and minidisk
Call Format
The format for calling a CSL routine is language dependent. DMSGETDF is called only through DMSCSL. The routine name is the first parameter in DMSCSL’s parameter list:
- DMSGETDF
- (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 DMSGETDF routine to read one directory record after a directory has been opened using the DMSOPDIR (Open Directory) routine with an intent of FILE. Immediately after Open Directory, Get Directory starts with the first directory entry. Each subsequent call gets the next directory entry.
Parameters
- retcode
- (output, INT, 4) is a variable for the return code from DMSGETDF.
- reascode
- (output, INT, 4) is a variable for the reason code from DMSGETDF.
- token
- (input, CHAR, 8) is a variable for passing the information returned by DMSOPDIR that uniquely identifies the open directory.
- fileid
- (output, CHAR, 16) is a variable used to return either the file name and file type as two adjacent 8-byte fields, or a subdirectory name.
- fm_no
- (output, CHAR, 1) is a variable (‘0’-‘6’ or a blank) in which the file mode number is returned.
- rd_auth
- (output, CHAR, 1) is a 1-byte character in which your read authority is returned:
- 0
- false (always returned for external objects)
- 1
- true
- ' ' (blank)
- check the extern_protect indicator
- ?
- authority for the subdirectory is not provided by this function. Use DMSGETDT (or the QUERY AUTHORITY command) to determine the authorization for the object.
- wr_auth
- (output, CHAR, 1) is a variable in which your write authority is returned:
- 0
- false (always returned for external objects)
- 1
- true (if minidisk file then the file was accessed read/write)
- ' ' (blank)
- check the extern_protect indicator
- ?
- authority for the subdirectory is not provided by this function. Use DMSGETDT (or the QUERY AUTHORITY command) to determine the authorization for the object.
- extern_protect
- (output, CHAR, 1) is a variable in which an indicator is returned to show whether the directory is externally protected; ‘0’ indicates no External Security Manager (ESM) protection; ‘1’ indicates ESM protection.
- status
- (output, CHAR, 1) is a variable in which the type of the file is returned:
- 1
- base file
- 2
- alias
- 3
- erased alias
- 4
- revoked alias
- 5
- directory
- 6
- external object
- 7
- minidisk file
- recform
- (output, CHAR, 1) is a variable used to return an indicator to show whether the file contains
fixed-length records; variable-length records; a directory; or an erased or revoked alias, or an
external object. Possible 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.
- D
- indicates that this is a directory record.
- - (hyphen)
- indicates that the file is an erased or revoked alias, or an external object. See status to determine which it is.
- rec_len
- (output, INT, 4) is a variable in which the record length for the file is returned. A nonzero value is only returned for base files and aliases.
- num_blks
- (output, INT, 4) is a variable used to return the number of blocks contained in the file. Zero is returned for external objects.
- num_recs
- (output, INT, 4) is a variable used to return the number of records contained in the file. Zero is returned for external objects.
- date
- (output, CHAR, 8 or 10) is a variable used to return the date-of-last-update of the file. For
external objects, this is the date it was created. 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 4-digit years returned. SHORTDATE is the default, which is the 2-digit year format.
Note that you must specify 10-character output fields if you specify FULLDATE or ISODATE; otherwise, you could get storage overlays.
- time
- (output, CHAR, 8) is a variable used to return the time the file was last updated or the external object was created, in the character format hh:mm:ss.
- owner_userid
- (output, CHAR, 8) is a variable used to return the user ID of the owner of the base file, directory, or external object. This file contains blanks for a minidisk file.
- wuerror
- (output, CHAR, length1) is a variable used to specify an area for returning work unit extended error information. If it is specified, it must be followed by a length field. See wuerror under Common Parameters for more information.
- length1
- (input, INT, 4) is a variable for specifying 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.
- dir_attr
- (output, CHAR, 1) is a variable in which the directory attribute is returned:
- 0
- indicates a file control directory.
- 1
- indicates a directory control directory.
- ' ' (blank)
- indicates that the returned record does not describe a directory.
- migrated
- (output, CHAR, 1) is a variable in which a file's migrated status is returned:
- 0
- indicates that file is not in DFSMS/VM migrated status
- 1
- indicates that file is in DFMS/VM migrated status
- ' ' (blank)
- is returned for objects with status values other than 1 (base file) or
2 (alias).
A file in migrated status is one which has been moved to storage owned and managed by DFSMS/VM.
- unique_id
- (output, CHAR, 16) is a value that uniquely identifies an object within a file pool: base file,
alias, alias of an erased file, revoked alias, or external object. It contains blanks for a minidisk
file. See usage note 5.
Certain administrative actions, such as reorganizing the file pool catalogs, can cause unique ID values to change, but the value for each object is always unique within the file pool.
- out_fm
- (output, CHAR, 1) is the file mode letter of the accessed minidisk or SFS directory.
- requestid
- (input/output, INT, 4) is a variable that identifies a specific asynchronous request. If it is omitted or contains binary 0 on input, the request is synchronous. If it contains a binary 1 on input, the request can be asynchronous. CMS returns an integer in requestid to identify an asynchronous request. This ID is passed on a later Check (DMSCHECK) request. CMS returns a 1 in requestid if the request was completed synchronously and it is not necessary to call DMSCHECK.
- 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. If the date format parameter is not specified, 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.
- length2
- (input, INT, 4) is a variable containing the length of the preceding character parameter (SHORTDATE, FULLDATE, or ISODATE).
Usage Notes
- If successful, the requested directory data is returned in the appropriate parameters.
- DMSGETDF also returns information about subdirectory entries within the directory specified on the call to Open Directory.
- A file-not-found error condition can occur even though the Open Directory indicated that the file does exist. This can happen if the file is present at the time of the Open Directory but is erased before the Get Directory call is issued.
- For performance, a question mark (?) is sometimes returned in rd_auth
and wr_auth for subdirectories. The question mark is returned for
subdirectories when all of the following are true:
- The opened (parent) directory is directory control.
- An External Security Manager is not being used
- You are not the owner of the subdirectory.
Use DMSGETDT or the QUERY AUTHORITY command to determine the authorization for these objects.
- Besides DMSGETDF, CSL routines DMSEXIST, DMSEXIFI, DMSGETDI, and DMSGETDX return the unique ID of an SFS file or directory. You can use DMSEXIST to obtain information about file pool objects identified by the unique ID and file pool ID.
- File pool servers that are not at the current release level do not support all of the DMSGETDF parameters. Rather than return error or warning codes, DMSGETDF tolerates down-level servers where possible. For the unsupported parameters, DMSGETDF returns values that are consistent with the functions provided by the down-level server. These values are listed in usage note 6, in the description of DMSGETDI.
- If the file resides on a minidisk, the read and write authorities returned indicate how the minidisk was accessed. The rd_auth variable will always be true and wr_auth will be true if the minidisk was accessed read/write.
- 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.
- 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.
- 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,
- If DMSGETDF is called from a program written in REXX, the date field returned will always be 10 characters in length. If the SHORTDATE format is specified or allowed to default, this field will be padded on the right with 2 blanks.
- If you want to perform arithmetic or conversion operations on the time stamps that are output from this routine, you may find the DateTimeSubtract CSL routine helpful. See z/VM: CMS Application Multitasking.
- If a DMSGETDF call is made immediately after an ACCESS of a minidisk, the returned directory entries are sorted alphabetically. If the minidisk is updated and not reaccessed, any new directory entries are returned at the end of the list of entries.
Return Codes and Reason Codes
For lists of the possible return codes from DMSGETDF, see Return Codes.
The following table lists the special reason codes returned by DMSGETDF. 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.
DMSGETDF 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 | 44040 | All of the selected data has been returned. Subsequent Get Directory requests will result in reason code 90275. |
ERROR | 90245 | Directory was opened for a different intent. It must be opened with intent of FILE. |
ERROR | 90260 | The directory has been closed. The directory was erased, or your authority to it was revoked. |
ERROR | 90275 | No data found for this Get Directory request. Your previous Get Directory request issued warning 44040 to indicate that all of the requested data has been returned. |
ERROR | 90310 | Incorrect option in CSL parameter list. Valid options are SHORTDATE, FULLDATE, or ISODATE. |
ERROR | 90320 | Conflicting options in CSL parameter list. SHORTDATE, FULLDATE, and ISODATE, if specified, are mutually exclusive parameters. |
ERROR | 90330 | Duplicate options in CSL parameter list. One or more of the following parameters were specified more than once: SHORTDATE, FULLDATE, and ISODATE. |
ERROR | 90415 | Incorrect length specified for the wuerror parameter. A nonzero length must be at least 12 bytes. |
ERROR | 90472 | Incorrect request ID specified; must be 0 or 1. |
ERROR | 95700 | System error. No open directory found for the specified token. |