DMSOPDIR - Open Directory

Read syntax diagramSkip visual syntax diagram DMSOPDIR , retcode , reascode , fn*ft*namedef1 dirnamefilemode*1bfsidnamedef2 fmnumber , length1 , FILEFORCEROFORCERWNOEXTEXTALIASAUTHDIRFILEEXTLOCKSEARCHALLSEARCHAUTH , length2 , token ,workunitid,wuerror,length3Group 1
Group 1
Read syntax diagramSkip visual syntax diagram , userdata , length4 Group 2
Group 2
Read syntax diagramSkip visual syntax diagram , requestid ,buffersize,number
Notes:
  • 1 * may be specified for filemode only when the open intent is FILE.

Context

File System Management: SFS, BFS, and minidisk

Call Format

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

DMSOPDIR
(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 DMSOPDIR routine to open an SFS directory, a byte file system, or a minidisk that is to be read later using any of the Get Directory routines.

Parameters

retcode
(output, INT, 4) is a variable for the return code from DMSOPDIR.
reascode
(output, INT, 4) is a variable for the reason code from DMSOPDIR.
fn ft
(input, CHAR, 3-17) is a variable for specifying the file name and file type of files in the directory being opened. For a BFS file, these are system-generated values. You can specify an asterisk (*) for either fn or ft to indicate all file names or all file types.
namedef1
(input, CHAR, 1-16) is a variable for specifying a temporary name previously created for fn_ft.
dirname
(input, CHAR, 1-153) is a variable for specifying the name of the SFS directory being opened.
filemode
(input, CHAR, 1) is a variable for specifying the file mode of an accessed minidisk or SFS directory to be opened. If this file mode letter is also a one-character temporary name, it is treated as a temporary name (namedef2) rather than a file mode.

An asterisk may be used to specify searching of all accessed minidisks and SFS directories, but only if the intent is FILE.

bfsid
(input, CHAR, 1-18) is a variable for specifying the name of the byte file system (BFS top directory) to be opened.
namedef2
(input, CHAR, 1-16) is a variable for specifying a temporary name previously created for a dirname, filemode, or bfsid.
fmnumber
(input, CHAR, 1) is a variable for specifying the file mode number. Only files with this file mode number will be passed on a later Get Directory. If not specified, all file mode numbers will be returned.
length1
(input, INT, 4) is a variable for specifying the length of the preceding compound character parameters (fn_ft or namedef1, if specified; plus dirname, filemode, bfsid, or namedef2; plus fmnumber, if specified). See Compound Variables for coding details.
FILE
(input, CHAR, 4) opens a directory for which a later Get Directory (DMSGETDF or DMSGETDI) will get information. You must specify the fn_ft or namedef1 parameter on input. Information returned from a later Get Directory will include:
  • File name
  • File type
  • File mode
  • File mode number
  • Record format
  • Logical record length
  • Number of records
  • Number of blocks
  • Date of last update
  • Time of last update
  • Owner
  • Type (directory, alias, base, erased, revoked)
  • Authority
  • Directory attribute

You can also open a minidisk “directory” using FILE. This will search for files on the minidisk specified by filemode.

For External Security Manager (ESM)-protected objects, a flag indicating that it is ESM-protected is returned, not the authorities. For the exact output format, see the description of the Get Directory routine (DMSGETDI).

This intent is not allowed for BFS.

FORCERO
(input, CHAR, 7) establishes a read-only status for a directory during the time it is open. This read-only status has no effect on file control directories, but does affect the use of directory control directories (see the Usage Notes). FORCERO can be specified only when the intent is FILE.
FORCERW
(input, CHAR, 7) establishes a read/write status for a directory during the time it is open. This read/write status has no effect on file control directories, but does affect the directory control directories (see the Usage Notes). FORCERW can be specified only when the intent is FILE.
EXT
(input, CHAR, 3) indicates that file mode extensions will be searched. When a filemode is specified and the intent is FILE, file searching will be done on the minidisk or SFS directory accessed at filemode and will continue on any file mode extension.
NOEXT
(input, CHAR, 5) indicates that file mode extensions will not be searched. This may only be specified with intent of FILE. If neither EXT or NOEXT is specified, NOEXT will be used as the default.
ALIAS
(input, CHAR, 5) opens a directory for which a later Get Directory (DMSGETDL or DMSGETDI) will get information. You must specify the fn_ft or namedef1 parameter. Information returned from a later Get Directory consists of: file name, file type, file mode number, format, logical record length, records, blocks, date, time, owner, type (alias, base, erased, revoked). For type=alias, the owner of the base file, base file name, file type, and directory name are also returned. The last three fields will be blank if you are not authorized for the directory. For the exact output information, see the Get Directory routine (DMSGETDI). For type=base, the owner of the alias, alias file name, file type, and directory name are also returned. The last three fields may be blank if you are not authorized for the directory. In this case, the number of aliases to the base file is returned instead.

You must have authority on the file name specified. If you use an ambiguous file ID, you must have authority on the directory.

AUTH
(input, CHAR, 4) opens a directory for which a later Get Directory (DMSGETDT or DMSGETDI) will get information about authorizations that the caller has or has granted to others.

You can specify the fn_ft or namedef1 parameter. Information returned from a later Get Directory (DMSGETDI) consists of: file name, file type, file mode number, type (base, alias, directory, erased, revoked), grantee, authority, and the directory attribute. The ESM-protected flag is also returned. If it is on, authorities are returned. However, these are the base authorities, not the ESM-held ones. For the exact output information, see the Get Directory routine (DMSGETDI).

You must have authority on the file name specified. If special characters (* or %) are specified, you must also have authority on the directory.

This intent is not allowed for BFS.

DIR
(input, CHAR, 3) opens a directory for which a later Get Directory (DMSGETDD or DMSGETDI) will get information. You must not specify the fn_ft or namedef1 parameter.

Calls to Get Directory return information about the directory and any subdirectories to which you have authority. For the exact output information, see the Get Directory routine (DMSGETDI) or the Get Directory - Dir routine (DMSGETDD).

FILEEXT
(input, CHAR, 7) opens a directory for which a later Get Directory (DMSGETDX or DMSGETDI) request will return extended information. You must specify fn_ft or namedef1 when you use FILEEXT. If you open a directory with FILEEXT, Get Directory returns all of the file attributes returned for FILE (except file mode), plus:
  • File space type (SFS or BFS)
  • Date of last reference
  • Date of creation
  • Time of creation
  • Recoverability
  • Overwrite
  • Date of last change
  • Time of last change

The extended attributes are returned only when FILEEXT is specified. For best performance, use FILE unless you need the extended attributes.

For the exact output format, see the description of the Get Directory routine (DMSGETDI) or the Get Directory - File Extended routine (DMSGETDX).

LOCK
(input, CHAR, 4) opens a directory for which a later Get Directory (DMSGETDK or DMSGETDI) routine will get information. You can specify the fn_ft or the namedef1 parameter. Information returned from a later Get Directory consists of: file name, file type, file mode number, type (base, alias, directory, erased, revoked), lock holder, and type of lock. For the exact output information, see the Get Directory routine (DMSGETDI).
SEARCHALL
(input, CHAR, 9) opens a directory for which later Get Directory calls (DMSGETDA or DMSGETDI) will get information. Information is made available only for objects that match the specified file ID in the specified directory and all its subdirectories.
DMSOPDIR searches only SFS subdirectories:
  • For which you have read or write authority
  • And which are not locked EXCLUSIVE by another user.

You must specify the fn_ft or namedef1 parameter on input. Information returned from a later Get Directory consists of: file name, file type, file mode number, format, logical record length, records, blocks, date, time, directory name, owner, type (directory, alias, base, erased, revoked), and the directory attribute. For the exact output information, see the Get Directory routine (DMSGETDI).

This intent is not allowed for BFS.

SEARCHAUTH
(input, CHAR, 10) is the same as SEARCHALL except that a later Get Directory (DMSGETDS or DMSGETDI) will only return information for files and subdirectories that the issuer is authorized for.
DMSOPDIR only searches SFS subdirectories:
  • For which you have read or write authority
  • That are not held by another user with an EXCLUSIVE lock.

For the exact output information, see the Get Directory routine (DMSGETDI).

This intent is not allowed for BFS.

length2
(input, INT, 4) is a variable for specifying the length of the preceding character parameter (FILE, and optionally FORCERO or FORCERW and EXT or NOEXT; or ALIAS, AUTH, DIR, FILEEXT, LOCK, SEARCHALL, or SEARCHAUTH). See Compound Variables for coding details.
token
(output, CHAR, 8) is a variable for returning a value that identifies an instance of an open directory. Pass the value of this variable on future calls to the Get Directory and Close Directory (DMSCLDIR) routines related to this Open Directory.
workunitid
(input, INT, 4) is a variable for specifying the work unit to be used for this operation. If you want to specify an optional parameter following workunitid without using the workunitid parameter, specify a value of 0 for the workunitid parameter.
wuerror
(output, CHAR, length3) 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. See wuerror under Common Parameters for more information.
length3
(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.
userdata
(input, CHAR, 1-80) is a variable for specifying a string of up to 80 characters of user data to be passed to an SFS external security manager (ESM). The ESM defines the format and meaning of the data (see the Usage Notes).
length4
(input, INT, 4) is a variable for specifying the length of the preceding character parameter (userdata). The value of length4 must not be greater than 80. Specifying 0 has the effect of omitting the userdata parameter.
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 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 (DMSCHECK) request.

If the returned request ID is still 1, no server call was needed, and it is not necessary to call DMSCHECK, because the function has already been completed.

buffersize
(output, INT, 4) is the length of the directory entry information associated with the specified intent keyword. Although the amount of directory entry information can be greater then 16KB, the maximum value that can be returned in buffersize is 16K + 1 (16 385 or X'0401'), which indicates that there is more than 16KB of directory information.

If a file is not specified or if the file ID is ambiguous, DMSOPDIR returns the total length of all the entries for the directory. If a file is specified, DMSOPDIR returns the length of all the directory entries associated with the file. If the intent is FILE, DMSOPDIR returns a buffersize of zero.

number
(output, INT, 4) is the number of directory entries associated with the specified directory. If there is more than 16KB of directory information, number contains the number of entries that fit into 16KB.

If a file is not specified or if the file ID is ambiguous, DMSOPDIR returns the number of entries for the directory. If a file is specified, the DMSOPDIR returns the number of entries associated with the file. If the intent is FILE, DMSOPDIR returns a number of zero.

Usage Notes

  1. No implicit locks are held across the Open Directory (DMSOPDIR), Get Directory (DMSGETDD, DMSGETDF, DMSGETDI, and so on), and Close Directory (DMSCLDIR) sequence. This means that while a directory is open, changes to information in the directory may or may not be reflected in subsequent Get Directory requests.

    When a directory is open, 16KB of data is sent to the user’s virtual machine for use by Get Directory. If changes are made while the directory is open, (for example, a file is erased) those changes are not reflected in the data in the user machine. However, if Get Directory needs to get another 16KB of data from the server, the changes may be reflected in the new set of data.

    An exception to this rule is when the directory is open for intent FILE. In this case, changes are immediately reflected and subsequent Get Directory requests reflect those changes. For example, if the directory is opened for intent FILE and a file in the directory is erased, subsequent Get Directory requests will not return an entry for that file. An exception to this exception is when the intent is FILE and the work unit used was gotten for another user ID (see DMSGETWU for more details). In this case, changes are not immediately reflected and subsequent Get Directory calls operate that same as intents other than FILE.

  2. You cannot open an empty directory with intent FILE or FILEEXT.
  3. You can open a minidisk directory for FILE to get information on specific files on that minidisk. See the Get Directory function for details on how the information differs between files on SFS directories and CMS minidisks.
  4. If you are opening a directory control directory, use the FORCERW or FORCERO parameters to get the level of sharing you need. If you intend only to read the directory or its files during the time you have the directory open, specify FORCERO. If, however, you intend to write to the directory or its files, specify FORCERW.

    When you omit FORCERO and FORCERW, CMS uses directory ownership to determine whether you will be allowed to read or write. (CMS follows the same rules it follows for the ACCESS command.) If you own the directory, for example, CMS will try to establish a read/write status for you. If you do not own the directory, CMS, by default, establishes a read-only status.

    Letting CMS establish a read/write status for you when you intend only to read will prevent other authorized users from writing to your directory control directory. Conversely, letting CMS establish a read-only status for you will prevent you from updating the directory control directory.

    The FORCERO and FORCERW parameters have no effect on the sharing of file control directories.

  5. You can specify the FILEEXT intent even if you are not sure whether the server managing the directory supports all of the extended file attributes. In this case, a 1 (for RECOVER) is returned for the recoverability attribute and zeros are returned for the remaining extended attributes on subsequent Get Directory requests. If you specify FILEEXT intent when the server managing the directory does not support the date of last reference attribute, however, you will receive an error message. If the server supports the date of last reference attribute but one has not been established for the file, zeros will be returned.
  6. When AUTH is specified, later Get Directory requests will find directories for which you have only NEWREAD or NEWWRITE authority (not READ or WRITE authority). For all other open intents, directories for which you have only NEWREAD or NEWWRITE authority are not found (reason code 44000 is returned).
  7. If your installation does not use an external security manager (ESM), do not specify the userdata parameter.

    If your installation does use an ESM, refer to the ESM documentation to determine whether you must specify userdata. The ESM documentation should also define the format and meaning of the data. The ESM might, for example, require you to specify a password for the directory you are opening. If the directory being opened is minidisk, the userdata is not used.

  8. 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.
  9. If you have an active asynchronous request for a file pool, you cannot issue other requests (except a rollback request) for the affected file pool on that same work unit.
  10. All minidisk requests are done synchronously.
  11. The buffersize and number output variables can be used by an application on a DMSGETDI request. Use buffersize as the length of buffer (length1) and number as the number of entries to be returned by DMSGETDI (number). However, if an ambiguous file ID is used on the DMSOPDIR request, the values in buffersize and number are for all the entries that fit into 16KB.
  12. For a BFS file space, only intents of FILEEXT, LOCK, ALIAS, and DIR are supported. File pool administration authority is required. Only information for BFS regular files is returned.
  13. Opening a directory with intent FILE causes CMS to access the SFS directory implicitly.

Return Codes and Reason Codes

For lists of the possible return codes from DMSOPDIR, see Return Codes.

The following tables lists the special reason codes returned by DMSOPDIR. ERROR means the request failed. Errors cause return code 8 or 12.

DMSOPDIR 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
ERROR 44000 For Open Directory for AUTH, LOCK, ALIAS, or FILEEXT, the specified directory or specified file does not exist or you are not authorized to read the directory.
ERROR 64200 The directory control directory you specified is empty. It has no files or subdirectories.
ERROR 65400 The operation cannot be performed against a BFS object.
ERROR 81058 Server failure. The specified directory was placed in a data space, but your authorization to that data space was revoked because of server failure. To regain your authorization to the data space, simply reexecute the routine when the server is available. (The server internally handles data space authorizations based on your authority to the directory.)
ERROR 90220 The specified file does not exist in the specified directory, or no files exist that match the specified wildcard pattern.
ERROR 90230 The specified directory does not exist or you are not authorized to it.
ERROR 90250 File ID must be specified for Open Directory for SEARCHALL, SEARCHAUTH, ALIAS, FILE, or FILEEXT.
ERROR 90255 File ID cannot be specified for Open Directory for DIR.
ERROR 90300 Invalid parameter specified. Type of Open Directory is invalid, extraneous keywords are present, or FORCERO/FORCERW specified without intent FILE.
ERROR 90350 Incorrect number of blank-delimited tokens in the fileid or dirname parameter. There must be at least one and not more than four tokens in the string.
ERROR 90410 Invalid length specified for one of the character variables.
ERROR 90415 Invalid length specified for the wuerror parameter. A nonzero length must be at least 12 bytes.
ERROR 90420 The file name in the fileid parameter is invalid. The file name is longer than 8 characters or contains an invalid character.
ERROR 90430 The file type in the fileid parameter is invalid. The file type is longer than 8 characters or contains an invalid character.
ERROR 90472 Invalid request ID specified; must be 0 or 1.
ERROR 90500 The specified dirname is invalid.
ERROR 90505 The specified directory name is an extended form of directory ID, such as +A. Only directory names or file mode letters are allowed on program function calls.
ERROR 90510 The namedef part of the fileid or dirname parameter is longer than 16 characters.
ERROR 90530 The namedef part of the fileid or dirname parameter does not exist or was used incorrectly. For example, a namedef that was created for a directory name was used where a namedef for a file name and file type was expected.
ERROR 90540 Specified work unit ID is incorrect.
ERROR 90590 There is no default file pool currently defined, and filepoolid was not specified as part of the dirname.
ERROR 90601 Directory is on a CMS minidisk and open intent was not FILE.