HFS Directory Services
Serena XML supports the following HFS directory functions for general use:
| • Create a Directory — *FILE SERVICE MKDIR | • List All Directory Contents — *FILE SERVICE LIST |
| • Delete a Directory — *FILE SERVICE RMDIR | • List Files in a Directory — *FILE FILES LIST |
| • Rename a Directory — *FILE SERVICE RENAME | • *List Directories in a Directory — FILE DIRS LIST |
...
Create a Directory — FILE SERVICE MKDIR
This function allocates an empty HFS directory on the host. The resulting data object has a "file type code" of 1. Access permissions for the resources requested must first be defined for you in your mainframe security system.
The XML service/scope/message names for a message to create an HFS directory are:
<service name="file">
<scope name="service">
<message name="mkdir">
FILE SERVICE MKDIR Requests
Data structure details for the <request> tag appear in Exhibit 8-1. All subtags are required.
Exhibit 8-1. FILE SERVICE MKDIR <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <createInterPath> | Required | 1 | String (1) | Include intermediate path in <pathName>? Y = Yes, include full path from installation root node as prefix to new directory name in <pathName> N = No, omit path; include only the name of the new directory in <pathName> |
| <pathName> | Required | 1 | String (1024), variable | Name of new directory, optionally prefixed by path from installation root. If <createInterPath> = Y, <pathName> includes full path name from install root plus name of new directory. If <createInterPath> = N, <pathName> is new directory name only. |
| <permissions> | Required | 1 | Integer (3), fixed | Unix access permissions for new directory, coded as 3-digit integer, where: 1st digit = owner permissions 2nd digit = group permissions |
| 3rd digit = permissions for all others Each digit takes one of the following values: 7 - Read, write/rename/delete, execute 6 - Read, write/rename/delete 5 - Read, execute 4 - Read only 3 - Write/rename/delete, execute 2 - Write/rename/delete only 1 - Execute only 0 - No access permitted |
FILE SERVICE MKDIR Results
No <result> data structure is returned in response to an XML HFS directory creation request. However, the reply message does return a standard <response> data structure to indicate the success or failure of the request.
Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.
Delete a Directory — FILE SERVICE RMDIR
This function deletes an HFS directory on the host. Access permissions for the resources requested must first be defined for you in your mainframe security system.
The XML service/scope/message names for a message to delete an HFS directory are:
<service name="file">
<scope name="service">
<message name="rmdir">
These tags appear in both requests and replies. Case is significant.
FILE SERVICE RMDIR Requests
Data structure details for the <request> tag appear in Exhibit 8-2. All subtags are required.
Exhibit 8-2. FILE SERVICE RMDIR <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <deleteContents> | Required | 1 | String (1) | If the directory is not empty, should the deletion go forward anyway, taking with it any subordinate files or directories? Y = Yes, delete even if the directory has content. N = No, don’t delete if the directory has content. |
| <pathName> | Required | 1 | String (1024), variable | Name of directory to be deleted, prefixed by path from installation root. |
FILE SERVICE RMDIR Results
No <result> data structure is returned in response to an XML HFS directory deletion request. However, the reply message does return a standard <response> data structure to indicate the success or failure of the request.
Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.
Rename a Directory — FILE SERVICE RENAME
This function renames an HFS directory (or file) on the host. Access permissions for the resources requested must first be defined for you in your mainframe security system.
The XML service/scope/message names for a message to rename an HFS directory are:
<service name="file">
<scope name="service">
<message name="rename">
These tags appear in both requests and replies. Case is significant.
FILE SERVICE RENAME Requests
Data structure details for the <request> tag appear in Exhibit 8-3. All subtags are required.
Exhibit 8-3. FILE SERVICE RENAME <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <fromPathName> | Required | 1 | String (1024), variable | Old name of directory, prefixed by path from installation root. |
| <replace> | Required | 1 | String (1) | If the new directory name is already in use, should that preexisting directory be deleted so the rename can proceed Y= Yes, replace any existing directory of the same name with the renamed directory. N = No, don’t rename if another directory with the same name already exists. |
| <toPathName> | Required | 1 | String (1024), variable | New name of directory, prefixed by path from installation root. |
FILE SERVICE RENAME Results
No <result> data structure is returned in response to an XML HFS directory rename request. However, the reply message does return a standard <response> data structure to indicate the success or failure of the request.
Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.
List All Directory Contents — FILE SERVICE LIST
This function lists allocation information for all Unix data object contained in an HFS directory. The listing includes both files and subdirectories. Subdirectories may be expanded recursively for listing. Other output filtering options also exist. Access permissions for the resources requested must first be defined for you in your mainframe security system.
The XML service/scope/message names for a message to list all contents of an HFS directory are:
<service name="file">
<scope name="service">
<message name="list">
These tags appear in both requests and replies. Case is significant.
Optimized variants of this service are:
-
List Files in a Directory — FILE FILES LIST
Same as FILE SERVICE LIST with subdirectories excluded from listing.
-
List Directories in a Directory — FILE DIRS LIST
Same as FILE SERVICE LIST with
set to 1.
FILE SERVICE LIST Requests
Data structure details for the <request> tag appear in Exhibit 8-4.
Exhibit 8-4. FILE SERVICE LIST <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <caseSensitive> | Required | 1 | String (1) | Treat values in <fileName> and <pathName> as case sensitive Y= Yes, respect case as typed in tags. N = No, normalize values to upper case. |
| <expandDirectory> | Required | 1 | String (1) | Expand and list contents of subdirectories? Y = Yes, expand & list subdirectories N = No, don’t expand subdirectories |
| <fileName> | Optional | 0 - 1 | String (256), variable | Name of a particular file, subdirectory, or other Unix data object in the directory identified by <pathName> whose allocation information should be listed. Path is not included. Wildcards ‘*" and ‘?’ may be used. If this tag is used, only the named data object is included in the returned listing. If omitted, all data objects of the type requested in <fileType> are listed. NOTE: Concurrent use of <fileName> and <fileType> is not recommended. If the actual file type of the data object in <fileName> conflicts with the value in <fileType>, no objects will be listed, even if an object with the requested name exists in the directory. |
| <fileType> | Optional | 0 - 1 | Integer (1) | Unix data object type desired in listing. If used, only objects of the type specified are listed. If omitted, all object types are listed. Values: 1 = Directory 2 = Character special file 3 = Regular file |
| 4 = Named pipe (FIFO) file 5 = Symbolic link (alias/shortcut to other file) 6 = Reserved for block special file 7 = Socket file NOTE: Concurrent use of <fileType> and <fileName> is not recommended. If the actual file type of the named data object conflicts with the value supplied in <fileType>, no data will be returned, even if a data object with the requested name exists in the directory. |
||||
| <pathName> | Required | 1 | String (1024), variable | Name of directory whose contents are to be listed, prefixed by path from installation root. |
FILE SERVICE LIST Results
Data structure details for the <result> tag appear in Exhibit 8-5. One result data structure is returned for each file, directory, or other Unix data object listed.
A standard <response> data structure is returned after the final <result> tag to indicate success or failure of the request and the completion of the listing if successful. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.
Exhibit 8-5. FILE SERVICE LIST <result> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <createdDate> | Required | 1 | Integer (8), fixed | Creation date in yyyyMMdd format. |
| <createdTime> | Required | 1 | Integer (6), fixed | Creation time in HHmmss format. |
| <fileFormat> | Optional | 0 - 1 | Integer (1) | Record formatting and delimiter convention used by listed file or data object. 0 = Not specified 1 = Binary data 2 = New line (NL) 3 = Carriage return (CR) 4 = Line feed (LF) 5 = CR & LF6 6 = LF & CR 7 7 = CR & NL NOTE: Not relevant for directories. |
| <fileGroupOwner> | Required | 1 | String (8), variable | User ID of file group owner associated with the listed file or data object. |
| <fileName> | Required | 1 | String (256), variable | Name of the current file, subdirectory, or other Unix data object listed. |
| <fileOwner> | Required | 1 | String (8), variable | User ID of owner associated with the listed file or data object. |
| <fileSize> | Optional | 0 - 1 | Integer (9), variable | File or directory size in bytes. Values 0 - 999999999. NOTE: For directories, size is for directory object itself, not for files within directory. |
| <fileType> | Required | 1 | Integer (1) | Unix data object type of listed file or subdirectory. Values: 1 = Directory 2 = Character special file 3 = Regular file 4 = Named pipe (FIFO) file 5 = Symbolic link (alias/shortcut to other file) 6 = Reserved for block special file 7 = Socket file NOTE: If <fileType> = 5, <linkName>, <linkType> will also be present. |
| <hashToken> | Optional | 0 - 1 | Integer (16), fixed | ZMF hash token stored with a component. Can be compared to a reference value to determine whether component has changed. NOTE: Not applicable to directories. |
| <lastAccessedDate> | Required | 1 | Integer (8), fixed | Date last accessed in yyyyMMdd format. |
| <lastAccessedTime> | Required | 1 | Integer (6), fixed | Time last accessed in HHmmss format. |
| <lastModifiedDate> | Required | 1 | Integer (8), fixed | Date last modified in yyyyMMdd format. |
| <lastModifiedTime> | Required | 1 | Integer (6), fixed | Time last modified in HHmmss format. |
| <linkCount> | Required | 1 | Integer (5), variable | Count of inbound links pointing to this data object. Allowed values 0 - 65536. For files (<fileType> ≠ 1) the link count is the number of hard links pointing to the file. Symbolic or soft links (<fileType> = 5)are not included in this count. For directories (<fileType> = 1), the link count is the number of subdirectories. |
| <linkName> | Optional | 0 - 1 | String (1024), variable | Name of file pointed to by the current link or alias, prefixed by path from installation root. NOTE: Required if <fileType> = 5, not applicable otherwise. |
| <linkType> | Optional | 0 - 1 | Integer (1) | Unix data object type of file identified in <linkName>. Values: 1 = Directory 2 = Character special file 3 = Regular file 4 = Named pipe (FIFO) file 5 = Symbolic link (alias/shortcut to other file) 6 = Reserved for block special file 7 = Socket file NOTE: Required if <fileType> = 5, not applicable otherwise. |
| <permissions> | Required | 1 | Integer (3), fixed | Unix access permissions for listed file or subdirectory. Coded as 3-digit integer, where: 1st digit = owner permissions 2nd digit = group permissions |
| 3rd digit = permissions for all others Each digit takes one of the following values: 7 - Read, write/rename/delete, execute 6 - Read, write/rename/delete 5 - Read, execute 4 - Read only 3 - Write/rename/delete, execute 2 - Write/rename/delete only 1 - Execute only 0 - No access permitted NOTE: For directories, "execute" permissions should be read as "open directory" or "view files in directory". |
||||
| <realPath> | Optional | 0 - 1 | string (1024), variable | Real path name. |
List Files in a Directory — FILE FILES LIST
This function lists all the files in an HFS directory. Under the covers, it is the same service as FILES SERVICE LIST with certain predefined request options and output filters built in. Access permissions for the resources requested must first be defined for you in your mainframe security system.
The XML service/scope/message names for a message to list only files in an HFS directory are:
<service name="file">
<scope name="files">
<message name="list">
These tags appear in both requests and replies. Case is significant.
FILE FILES LIST Requests
Data structure details for the <request> tag appear in Exhibit 8-6. All subtags shown are required. Request tags <fileName> and <fileType> should not be used.
Exhibit 8-6. FILE FILES LIST <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <caseSensitive> | Required | 1 | String (1) | Treat values in <fileName> and <pathName> as case sensitive? Y = Yes, respect case as typed in tags. N = No, normalize values to upper case. |
| <expandDirectory> | Required | 1 | String (1) | Expand and list contents of subdirectories? Y = Yes, expand & list subdirectories N = No, don’t expand subdirectories |
| <pathName> | Required | 1 | String (1024), variable | Name of directory whose contents are to be listed, prefixed by path from installation root. |
| <returnHashToken> | Required | 1 | String (1) | Return a ZMF hash token with the listed files? Y = Yes, return hash token for files N = No, don’t return hash token |
FILE FILES LIST Results
Data structure details for the <result> tag appear in Exhibit 8-7. One result data structure is returned for each file listed.
A standard <response> data structure is returned after the final <result> tag to indicate success or failure of the request and the completion of the listing if successful. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.
Exhibit 8-7. FILE FILES LIST <result> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <createdDate> | Required | 1 | Integer (8), fixed | Creation date in yyyyMMdd format. |
| <createdTime> | Required | 1 | Integer (6), fixed | Creation time in HHmmss format. |
| <fileFormat> | Optional | 0 - 1 | Integer (1) | Record formatting and delimiter convention used by listed file. 0 = Not specified 1 = Binary data 2 = New line (NL) 3 = Carriage return (CR) 4 = Line feed (LF) 5 = CR & LF6 6 = LF & CR 7 7 = CR & NL |
| <fileGroupOwner> | Required | 1 | String (8), variable | User ID of file group owner. |
| <fileName> | Required | 1 | String (256), variable | Name of listed file. |
| <fileOwner> | Required | 1 | String (8), variable | User ID of file owner. |
| <fileSize> | Optional | 0 - 1 | Integer (9), variable | File size in bytes. Values 0 - 999999999. NOTE: For directories, size is for directory object itself, not for files within directory. |
| <fileType> | Required | 1 | Integer (1) | Unix data object type of listed file. Values: 2 = Character special file 3 = Regular file 4 = Named pipe (FIFO) file 5 = Symbolic link (alias/shortcut to other file) 6 = Reserved for block special file 7 = Socket file NOTE: If <fileType> = 5, <linkName> and <linkType> will also be present. |
| <hashToken> | Optional | 0 - 1 | Integer (16), fixed | ZMF hash token stored with a component. Can be compared with a stored value to determine whether the component has changed. |
| <lastAccessedDate> | Required | 1 | Integer (8), fixed | Date last accessed in yyyyMMdd format. |
| <lastAccessedTime> | Required | 1 | Integer (6), fixed | Time last accessed in HHmmss format. |
| <lastModifiedDate> | Required | 1 | Integer (8), fixed | Date last modified in yyyyMMdd format. |
| <lastModifiedTime> | Required | 1 | Integer (6), fixed | Time last modified in HHmmss format. |
| <linkCount> | Required | 1 | Integer (5), variable | Count of inbound hard links pointing to this file. Symbolic or soft links (aliases/shortcuts) are not included in count. Allowed values 0 - 65536. |
| <linkName> | Optional | 0 - 1 | String (1024), variable | Name of file pointed to by the listed link file (ie alias or shortcut) in <fileName>, prefixed by path from installation root. NOTE: Required if <fileType> = 5, not applicable otherwise. |
| <linkType> | Optional | 0 - 1 | Integer (1) | Unix data object type of file or data object identified in 1 = Directory 2 = Character special file 3 = Regular file 4 = Named pipe (FIFO) file 5 = Symbolic link (alias/shortcut to other file) 6 = Reserved for block special file 7 = Socket file NOTE: Required if |
| <permissions> | Required | 1 | Integer (3), fixed | Unix access permissions for listed file. Coded as 3-digit integer, where: 1st digit = owner permissions 2nd digit = group permissions 3rd digit = permissions for all others Each digit takes one of the following values: 7 - Read, write/rename/delete, execute 6 - Read, write/rename/delete 5 - Read, execute 4 - Read only 3 - Write/rename/delete, execute 2 - Write/rename/delete only 1 - Execute only 0 - No access permitted NOTE: For directories, "execute" permissions should be read as "open directory" or "view files in directory". |
| <realPath> | Optional | 0 - 1 | string (1024), variable | Real path name. |
List Directories in a Directory — FILE DIRS LIST
This function lists all the subdirectories in an HFS directory. Under the covers, it is the same service as FILES SERVICE LIST with certain predefined request options and output filters built in. Access permissions for the resources requested must first be defined for you in your mainframe security system.
The XML service/scope/message names for a message to list only subdirectories in an HFS directory are:
<service name="file">
<scope name="dirs">
<message name="list">
These tags appear in both requests and replies. Case is significant.
FILE DIRS LIST Requests
Data structure details for the <request> tag appear in Exhibit 8-8. All subtags shown are required. Request tags <fileName>, <fileType>, and <returnHashToken> should not be used.
Exhibit 8-8. FILE DIRS LIST <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <caseSensitive> | Required | 1 | String (1) | Treat values in <fileName> and <pathName> as case sensitive? Y = Yes, respect case as typed in tags. N = No, normalize values to upper case. |
| <expandDirectory> | Required | 1 | String (1) | Expand and list contents of subdirectories? Y = Yes, expand & list subdirectories N = No, don’t expand subdirectories |
| <pathName> | Required | 1 | String (1024), variable | Name of directory whose contents are to be listed, prefixed by path from installation root. |
FILE DIRS LIST Results
Data structure details for the <result> tag appear in Exhibit 8-9. One result data structure is returned for each subdirectory listed.listed. File-specific subtags such as <fileFormat>, <hashToken>, <linkName>, and <linkType> are not returned.
A standard <response> data structure is returned after the final <result> tag to indicate success or failure of the request and the completion of the listing if successful. Successful requests have a return code of 00. Unsuccessful requests have a return code of 04 or higher.
Exhibit 8-9. FILE DIRS LIST <result> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <createdDate> | Required | 1 | Integer (8), fixed | Creation date in yyyyMMdd format. |
| <createdTime> | Required | 1 | Integer (6), fixed | Creation time in HHmmss format. |
| <fileGroupOwner> | Required | 1 | String (8), variable | User ID of file group owner associated with this subdirectory. |
| <fileName> | Required | 1 | String (256), variable | Name of listed subdirectory. |
| <fileOwner> | Required | 1 | String (8), variable | User ID of file owner associated with this directory |
| <fileType> | Required | 1 | Integer (1) | Unix data object type of listed directory. Values: 1 = Directory |
| <lastAccessedDate> | Required | 1 | Integer (8), fixed | Date last accessed in yyyyMMdd format. |
| <lastAccessedTime> | Required | 1 | Integer (6), fixed | Time last accessed in HHmmss format. |
| <lastModifiedDate> | Required | 1 | Integer (8), fixed | Date last modified in yyyyMMdd format. |
| <lastModifiedTime> | Required | 1 | Integer (6), fixed | Time last modified in HHmmss format. |
| <linkCount> | Optional | 0 - 1 | Integer (5), variable | Count of subdirectories within the listed directory. Allowed values 0 - 65536. |
| <permissions> | Required | 1 | Integer (3), fixed | Unix access permissions for listed subdirectory. Coded as 3-digit integer, where: 1st digit = owner permissions 2nd digit = group permissions 3rd digit = permissions for all others Each digit takes one of the following values: 7 - Read, write/rename/delete, execute 6 - Read, write/rename/delete 5 - Read, execute 4 - Read only |
| 3 - Write/rename/delete, execute 2 - Write/rename/delete only 1 - Execute only 0 - No access permitted NOTE: For directories, "execute" permissions should be read as "open directory" or "view files in directory". |
||||
| <realPath> | Optional | 0 - 1 | string (1024), variable | Real path name. |