HFS File Lifecycle Services
The XML Services API supports the following HFS file lifecycle functions for general use:
| • Create a File — FILE *SERVICE CREATE | • Create a Link or Alias to a File *— FILE SERVICE LINK |
| • Delete a File — FILE *SERVICE DELETE | • Change File Attributes — *FILE SERVICE CHANGE |
| • Rename a File — FILE *SERVICE RENAME | • Check Access to a File — *FILE SERVICE ACCESS |
| • Copy a File — FILE *SERVICE COPY | • Scan Files for Strings — FILE *SERVICE SCAN |
Create a File — FILE SERVICE CREATE
This function allocates an empty HFS file on the host. The resulting data object has a "file type code" of 3. 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 file are:
<service name="file">
<scope name="service">
<message name="create">
These tags appear in both requests and replies. Case is significant.
FILE SERVICE CREATE Requests
Data structure details for the <request> tag appear in Exhibit 8-10. All subtags are required.
Exhibit 8-10. FILE SERVICE CREATE <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 in <pathName> value N = No, omit path; include only the name of the new file in <pathName> |
| <pathName> | Required | 1 | String (1024), variable | Name of new file to be created, optionally prefixed by path from installation root. If <createInterPath> = Y, <pathName> includes full path from installation root plus name of new file. If <createInterPath> = N, <pathName> is new file name only. |
| <permissions> | Required | 1 | Integer (3), fixed | Unix access permissions for new 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". |
FILE SERVICE CREATE Results
No <result> data structure is returned in response to an XML HFS file 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 File — FILE SERVICE DELETE
This function deletes an HFS 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 delete an HFS file are:
These tags appear in both requests and replies. Case is significant.
FILE SERVICE DELETE Requests
Data structure details for the <request> tag appear in Exhibit 8-11. All subtags are required.
Exhibit 8-11. FILE SERVICE DELETE <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <pathName> | Required | 1 | String (1024), variable | Name of file to be deleted, prefixed by path from installation root. |
FILE SERVICE DELETE Results
No <result> data structure is returned in response to an XML HFS file 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 File — FILE SERVICE RENAME
This function renames an HFS file (or 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 rename an HFS file 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-12. All subtags are required.
Exhibit 8-12. FILE SERVICE RENAME <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <fromPathName> | Required | 1 | String (1024), variable | Old name of file to be renamed, prefixed by path from installation root. |
| <replace> | Required | 1 | String (1) | If the new file name is already in use, should the preexisting file be deleted so the rename can proceed? Y = Yes, replace any existing file of the same name with the renamed file. N = No, don’t rename if another file with the same name already exists. |
| <toPathName> | Required | 1 | String (1024), variable | New name of file, prefixed by path from installation root. |
FILE SERVICE RENAME Results
No <result> data structure is returned in response to an XML HFS file 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.
Copy a File — FILE SERVICE COPY
This function makes an identical copy of an HFS 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 copy an HFS file are:
<service name="file">
<scope name="service"> <message name="copy">
These tags appear in both requests and replies. Case is significant.
FILE SERVICE COPY Requests
Data structure details for the <request> tag appear in Exhibit 8-13. All subtags are required.
Exhibit 8-13. FILE SERVICE COPY <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <compression> | Required | 1 | String (1) | Compress the target file during copy? Y = Yes, compress the target file. N = No, do not compress the target file. E = Expand the target file if the source file is compressed. |
| <copyTimeStamp> | Optional | 0 - 1 | String (1) | Copy all source timestamps to target file? Y = Yes, copy all timestamps from source file to target file N = No, update modification and access dates/times in target file at copy time (default). |
| <fromPathName> | Required | 1 | String (1024), variable | Name of source file to be copied, prefixed by path from installation root. |
| <replace> | Required | 1 | String (1) | If a file with the desired name already exists, should the preexisting file be deleted so the copy operation can proceed? Y = Yes, replace any existing file of the same name with the copied file. N = No, cancel copy if another file with the desired name already exists. |
FILE SERVICE COPY Results
No <result> data structure is returned in response to an XML HFS file copy 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.
Create a Link or Alias to a File — FILE SERVICE LINK
This function creates a symbolic link — also known as an alias or shortcut — to an HFS file. The resulting data object has a "file type code" of 5. Appropriate 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 a link to an HFS file are:
These tags appear in both requests and replies. Case is significant.
FILE SERVICE LINK Requests
Data structure details for the <request> tag appear in Exhibit 8-14. All subtags are required.
Exhibit 8-14. FILE SERVICE LINK <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <linkPathName> | Required | 1 | String (1024), variable | Name of target file, prefixed by path from installation root. NOTE: This file or data object must already exist for link to be created. |
| <pathName> | Required | 1 | String (1024), variable | Name of symbolic link file that will point to target, prefixed by path from installation root. NOTE: This object will be created with file type = 5. |
FILE SERVICE LINK Results
No <result> data structure is returned in response to an XML HFS file link 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.
Change File Attributes — FILE SERVICE CHANGE
This function changes selected attributes, such as access permissions, for an HFS file (or directory) on the host. Appropriate access permissions for the resources requested must first be defined for you in your mainframe security system. You must be the file owner or an administrator to change access permissions.
The XML service/scope/message names for a message to change attributes of an HFS file are:
These tags appear in both requests and replies. Case is significant.
FILE SERVICE CHANGE Requests
Data structure details for the <request> tag appear in Exhibit 8-15. In addition to the mandatory
Exhibit 8-15. FILE SERVICE CHANGE <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <format> | Optional | Changes the format of a file. Possible values are x'F0' through x'F8' corresponding to the UNIX file formats shown below: | ||
| ** File format definitions (for chattr) | ||||
FTFFNA EQU 0 Not specified |
||||
FTFFBINARY EQU 1 Binary data |
||||
* Text data delimiters: |
||||
FTFFNL EQU 2 New Line |
||||
FTFFCR EQU 3 Carriage Return |
||||
FTFFLF EQU 4 Line Feed |
||||
FTFFCRLF EQU 5 CR & LF |
||||
FTFFLFCR EQU 6 LF & CR |
||||
FTFFCRNL EQU 7 CR & NL |
||||
* Data consists of Records: |
||||
FTFFRECORD EQU 8 Records |
||||
| <modTime> | Optional | 0 - 1 | Integer (14), fixed | New value for modification date and time. Format is yyyyMMddHHmmss. |
| <pathName> | Required | 1 | String (1024), variable | Name of file (or directory) to change, prefixed by path from installation root. |
| <permissions> | Optional | 0 - 1 | Integer (3), fixed | New Unix access permissions for 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: You must be the file owner or an administrator to change access permissions. NOTE: For directories, “execute” permissions should be read as “open directory” or “view files in directory”. NOTE: You must be the file owner or an administrator to change access permissions. |
FILE SERVICE CHANGE Results
No <result> data structure is returned in response to an XML HFS file parameter change 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.
Check Access to a File — FILE SERVICE ACCESS
This function checks for the existence of an HFS file (or directory) on the host, or for access permissions available to you (or another current user) if the file exists. Access permissions for the resources requested must first be defined for you (or the other user) in your mainframe security system.
USE CASES
-
To determine whether a particular file (or directory) exists on a particular path, submit this request with
set to 8. If the file exists, the return code will be 00. If it does not exist, the return code will be 08. -
To determine whether the current user of the service has permission to execute the named file, submit this request with
set to an odd number from 1 to 7, using Unix numeric permission conventions. In other words, set it to 1 (execute permissions only), 3 (write/rename/delete and execute permissions), 5 (read and execute permissions), or 7 (read, write/rename/delete, and execute permissions). If the user has the requested level of access to the file, the service will reply with a return code of 00. If the user does not have the requested level of access, the return code will be 08.
SYNTAX
The XML service/scope/message names for a message to check access to an HFS file are:
These tags appear in both requests and replies. Case is significant.
FILE SERVICE ACCESS Requests
Data structure details for the <request> tag appear in Exhibit 8-16. All subtags are required.
Exhibit 8-16. FILE SERVICE ACCESS <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <accessMode> | Required | 1 | String (1) | Type of file access to be tested. May test file existence or access permissions for current user. Values: 8 - File exists 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/list files in directory". |
| <pathName> | Required | 1 | String (1024), variable | Name of file (or directory) to be accessed, prefixed by path from installation root. |
...
FILE SERVICE ACCESS Results
No <result> data structure is returned in response to an XML HFS file access check 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.
Scan Files for Strings — FILE SERVICE SCAN
This function scans HFS files for requested strings.
The XML service/scope/message names for a message to scan files are:
<service name="file">
<scope name="service">
<message name="scan">
These tags appear in both requests and replies. Case is significant.
FILE SERVICE SCAN Requests
Data structure details for the <request> tag appear in Exhibit 8-17.
Exhibit 8-17. FILE SERVICE SCAN <request> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <and> | Optional | 0 - 1 | String (1) | To connect strings 1 and 2 (<scan1> and <scan2>). Y = connect strings N = do not connect strings |
| <caseFile> | Optional | 0 - 1 | String (1) | Case-sensitivity of file name. Y = file name is case-sensitive. N = file name is not case-sensitive. |
| <caseSensitive> | Optional | 0 - 1 | String (1) | Case-sensitivity of search strings. Y = search strings are case-sensitive. N = search strings are not case-sensitive. |
| <endOffset> | Optional | 0 - 1 | Integer | Displacement end. |
| <fileName> | Optional | 0 - 1 | String (256), variable | Name of file to be scanned. |
| <listType> | Optional | 0 - 1 | String (1) | Short or long result list. S = Short L = Long |
| <maxHits> | Optional | 0 - 1 | Integer | Maximum hits. 0 = unlimited. |
| <pathName> | Optional | 0 - 1 | String (1024), variable | Name of path to be scanned. |
| <recurse> | Optional | 0 - 1 | String (1) | Search subdirectories. Y = Search through all subdirectories. N = Search only the directory specified in <pathName>. |
| <scan1> | Optional | 0 - 1 | String (40), variable | Scan string 1. |
| <scan2> | Optional | 0 - 1 | String (40), variable | Scan string 2. |
| <startOffset> | Optional | 0 - 1 | Integer | Displacement end. |
FILE SERVICE SCAN Results
Data structure details for the <result> tag appear in Exhibit 8-18. One to many <data> tags are 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-18. FILE SERVICE SCAN <result> Data Structure
| Subtag | Use | Occurs | Data Type & Length | Values & Dependencies |
|---|---|---|---|---|
| <data> | Optional | 1 - ∞ | String, variable | Line of data. Includes file line, summary line, and matching line. |