Filesystems/{filesystemName}/file/{path}/fileSize/{size}: POST

Creates a file of specified size in a GPFS file system and assigns a user, a group, or both as its owner.

Availability

Available with IBM Storage Scale Erasure Code Edition only.

Description

The POST filesystems/{filesystemName}/file/{path}/fileSize/{size} request creates a file in a GPFS file system and assigns a user, a group, or both as its owner. You can specify the size of the file that you want to create. You can provide both the ID and the name of the user or group in the request parameter. When the file is created the user or group ID, and not the name, is displayed to indicate the file owner in the log that is generated.

Request URL

https://<IP address or host name of API server>:port/scalemgmt/v2/filesystems/filesystemName/file/path/fileSize/size

Request headers

Accept: application/json

Request data

The following list of attributes is available in the request data:

{
  "user": "String",
  "uid": Integer,
  "group": "String",
  "gid": Integer 
  "recursive": true | false

  }
The details of the parameters are given in the following list:
"user": Owner name
The name of the user who owns the file.
"uid": User ID
The unique identifier of the user who owns the file.
"group": Owner group
The name of the user group that owns the file.
"gid" : Group ID
The unique identifier of the user group that owns the file.
"permission":"Access permissions"
The number of permissions that are set by using the CLI command chmod. If nothing is specified, then no action is allowed.
"recursive":"true | false"
Specifies whether the owner is defined recursively for the entire file system or for the specific directory that is defined in the endpoint path.

Parameters

Table 1. List of parameters
Parameter name Description and applicable keywords Required/Optional
filesystemName Name of the GPFS file system where the file is created. Required
path The directory location. The path that is provided is relative to the file system's mount point. Required
size The size of the new file. Required
body The request body. Required

Response data

{
   "status": {
      "code":ReturnCode",
      "message":"ReturnMessage"
   },
   "jobs": [
      {
         "result":"", 
           { 
             "commands":"String",
             "progress":"String,
             "exitCode":"Exit code",
             "stderr":"Error",
             "stdout":"String",
           },
         "request":" ",
           {
             "type":"{GET | POST | PUT | DELETE}",
             "url":"URL",
             "data":""",
           }
         "jobId":"ID",
         "submitted":"Date and Time",
         "completed":"Date and Time",
         "runtime":Duration",
         "status":"Job status",
         "pids":"Process IDs
         }
   ],
  }

The details of the parameters are provided in the following list:

"jobs":
An array of elements that describe jobs. Each element describes one job.
"status":
Return status.
"message": "ReturnMessage",
The return message.
"code": ReturnCode
The return code.
"result"
"commands":"String"
Array of commands that are run in this job.
"progress":"String"
Progress information for the request.
"exitCode":"Exit code"
Exit code of command. Zero is success and nonzero denotes failure.
"stderr":"Error"
CLI messages from stderr.
"stdout":"String"
CLI messages from stdout.
"request"
"type":"{GET | POST | PUT | DELETE}"
HTTP request type.
"url":"URL"
The URL through which the job is submitted.
"data":
Optional.
"jobId":"ID",
The unique ID of the job.
"submitted":"Date and Time"
Specifies the date and the time at which the job was submitted.
"completed":"Date and Time"
Specifies the date and the time at which the job was completed.
"runtime":"Duration"
Specifies the duration for which the job ran.
"status":"RUNNING | COMPLETED | FAILED"
Specifies the status of the job.
"pids":" Process ID"
Specifies the process IDs of all the active sub processes that manage the job.

Examples

The following example shows how to create a new file of size 1G.

Request data - 
 curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Basic YWRtaW46YWRtaW4wMDE=' -d '{ \ 
   "user": "testuser55", \ 
   "uid": 1234, \ 
   "group": "mygroup", \ 
   "gid": 4711,
   "recursive": false, \
   "permission": 700 \  
 }' 'https://9.114.204.107:2008/scalemgmt/v2/filesystems/NewFS/file/12Fmyfile.img/fileSize/1G'

Response data:

Note: In the JSON data that is returned, the return code indicates whether the command is successful. The response code 200 indicates that the command successfully retrieved the information. Error code 400 represents an invalid request and 500 represents internal server error. 
{
  "jobs" : [ {
    "jobId" : 1000000000003,
    "status" : "COMPLETED",
    "submitted" : "2021-01-30 18:01:45,173",
    "completed" : "2021-01-30 18:01:45,737",
    "runtime" : 563,
    "request" : {
      "type" : "POST",
      "url" : "/scalemgmt/v2/filesystems/NewFS/file/12Fmyfile.img/fileSize/1G"
      "data": " "user": "testuser55",
                "uid": 1234,
                "group": "mygroup",
                "gid": 4711"
    },
    "result" : {
      "progress" : [ ],
      "commands" : [ "fallocate -l length filename" ],
      "stdout" : [ " " ],
      "stderr" : [ ],
      "exitCode" : 0
    },
    "pids" : [ ]
  } ],
  "status" : {
    "code" : 200,
    "message" : "The request finished successfully."
  }
}