File Descriptor

A file descriptor describes a file and optionally, the structure of the file. The file can be located both in the Eclipse workspace or in the system to be attached.

The physical name (attribute Name_Physical) of the file does not have to be given in order to describe a file. This can be set by a tool output parameter at run time. If the physical name of the file already exists, a static value can be entered under this attribute. If only the structure of the file path has been specified, a dynamic path can be entered using dynamic references. See Variable References for more information.

A further feature of a file descriptor is the type. The Workspace_File type, indicates files that should be saved in the workspace or should be read from the workspace.

Attribute Type Description
ID * ID * The ID of the file descriptor.
Name_Physical [O] String The physical name of the file under which the target system can find the file (file path + file name).

You can specify dynamic references.

PropDelimiter String The delimiter to be used for the interpretation of structured file content.

The default value is " " (Blank).

Structure Selection Describes the structure of the file.  

Permitted values:

  • Unstructured (standard value)
  • Table
  • JSON
Type Selection The type of the file descriptor. This value specifies how the described file should be interpreted.  

Permitted values:

  • InputStream
  • Local_File
  • Workspace_File (standard value)

The following values can only be used at run time if EDc, EDz, or IDz is installed:

  • MVS_PO
  • MVS_PO_Member
  • MVS_SEQ
  • USS_File
Relationship Cardinality Description
Has_Property 0..* Relationship to a Property. Property values can be assigned to a file content, which enables editing of the content.

This relationship can only be used for the description of structured files (table structure).

Has_Action 0..* Relationship to an action descriptor. Used only if the file descriptor is of structured table and the table is part of a modeled dialog or an ISPF dialog. In this case the actions appear in the context menu of the table items.

File Descriptor Structure

A file descriptor can specify the following structures:

Unstructured
The file descriptor structure Unstructured, describes a flat file whose format is not known to AWM and not interpreted by AWM.
Table
The file descriptor structure Table, describes a file consisting of lines with a defined format. The way that AWM interprets the file is determined by the property delimiter (attribute: PropDelimiter) and the properties related to the file descriptor. Each line of the file will consist of values for the related properties separated by the property delimiter in the sequence of the property relation definition. At run time the values in the file are mapped to the properties as specified in the file descriptor to property relations. You can set a static value for a property reference. In this case the static value is mapped to each line of the table structured file at the corresponding position and set from or returned in the property referenced in the Target ID attribute of the property reference when writing or reading the file.

A file descriptor modelled in this way:


Table File Descriptor

Could have the following content:

Argentina,Buenos Aires,South America
Algeria,Alger,Africa
Niger,Niamev,Africa
France,Paris,Europe
JSON
The file descriptor structure JSON can be used to model a JSON payload, for example, for a REST service call. If the file descriptor is intended to parse a JSON payload it is only necessary to model the part of the JSON which is relevant for the AWM application. The JSON file structure should describe which parts of the JSON payload should be mapped to AWM properties.

At every level of the structure you can model a child of type 'Element' or 'Attribute'. An element can be a JSON object, an array or a simple array specified in the element's Type attribute. A JSON attribute can be one of the following types, String, Boolean, and Number. The JSON attribute can be specified as a static value or it can point to a property via the Target ID attribute. If the JSON attribute is pointing to a property via a Target ID the attribute value is taken from the current value of the property at run time and the property value is set by the value returned in the corresponding JSON attribute.

JSON array elements represent object arrays, which contain additional elements or attributes. Simple arrays are non-object arrays which only contain String, Numeric, or Boolean values. Similar to attributes, their values can be mapped to or taken from a modelled property or can be a static value. AWM currently only supports single-value simple attributes. Attempting to parse a JSON document with a multi-value simple array will result in an error message.

A file descriptor structure JSON has the additional action Generate Structure in the context menu of the model editor. This action enables you to generate the file descriptor's structure based on a given JSON payload. Calling this action opens the Generate Structure wizard. The wizard enables you to paste a JSON formatted payload in the editor window. Typically REST based applications offer a feature to capture the payload sent with a request. This payload capture can be cut and pasted into the wizard's editor window.

Clicking Preview displays the elements of the structure which will be added to the file descriptor's structure definition. The generation does not overwrite pre-existing elements of the file descriptor. If the JSON structure cannot be successfully parsed, an error message is displayed in the header of the wizard when clicking Preview or Finish. When you click Finish and no JSON parser errors are encountered, the file descriptor's structure is generated in the model editor. The type of an attribute (String, Number, or Boolean) is generated depending on the value type of the attribute in the given JSON payload.

This function can be used to simplify the task of modeling a complex JSON file descriptor structure. You will need to perform some clean up work after the generation, for example, setting the target id and static value of attributes, removing elements that are not required, and setting the mandatory attribute of elements where required.

The section below gives some guidance on how a JSON structured file descriptor is interpreted during run time.

You can specify a JSON file descriptor structure with objects and attributes that have missing values. If a specified non-mandatory object does not exist, AWM will skip it and continue parsing or generating the rest of the JSON document.

If a JSON object or attribute is specified as mandatory, AWM will enforce that it is present in the parsed JSON document or a property value is available when the JSON output is generated. If it is not, an error message is triggered and the parsing/generation process is stopped.

A file descriptor modelled in this way:


JSON File Descriptor

Could, for example, produce the following JSON payload at run time:

{
	"fields": {
		"summary": "No REST for the Wicked.",
		"issuetype": {
			"id": "Error"
		},
		"project": {
			"id": "10110"
		},
		"description": "Creation of an issue using IDs for projects and issue type."
	}
}

If a JSON document is returned by a tool descriptor, AWM is able to create an element list from it. If the document describes more than one item, it must contain an array. AWM will attempt to create one element for each array value. If the JSON output contains other attributes outside the array object, the attributes' values will be added to each parsed element, provided they have been specified in the file descriptor and mapped to properties.

Note: JSON documents containing more than one array are currently not supported. AWM will still attempt to parse the document, but the result might not be as expected. Any JSON file descriptors with more than one array will cause a validation warning in the AWM model editor.

Examples

File Descriptor SCLM_FILE_ElelistMember


File Descriptor SCLM_File_ElelistMember

File Descriptor SCLM_FILE_ElelistMember Properties
Attribute Value Description
Essential:
ID SCLM_FILE_ElelistMember Unique identifier of the file descriptor in this model.
Prop Delimiter "," Comma is used as the delimiter in the returned file to separate the values for the properties.
Structure Table A table structured file descriptor consists of a sequence of properties. The file has to provide in each line the values for every property specified as a File Descriptor_Has_Property relationship.
Type MVS_SEQ The format of the file is a MVS sequential file.
Optional:
Name Physical --- The physical name is not needed as the file descriptor is modeled as file output parameter of an ISPF command tool. The REXX procedure associated with the ISPF command tool returns the file name.

Example content of a SCLM_FILE_ElelistMember file descriptor:

MFI01V,MFIJKH,SCLMTEST,SOURCE,BBANKJKP,MFIJKH,2016/02/05 11:01:22,0,,EDITABLE
MFI01V,MFIJKH,SCLMDEV,SOURCE,BBANKJKP,MFIJKH,2016/03/11 03:57:01,0,,EDITABLE
MFI01V,MFIJKH,SCLMPROD,SOURCE,BBANKZZP,MFIJSS,2014/10/13 12:17:06,0,,EDITABLE

File Descriptor SCLM_FILE_SclmMember


File Descriptor SCLM_FILE_SclmMember
Attribute Value Description
Essential:
ID SCLM_FILE_SclmMember Unique identifier of the file descriptor in this model.
Prop Delimiter " " Not applicable as it is an unstructured file descriptor.
Structure unstructured The file has no internal structure.
Type MVS_PO_Member The format of the file is a member of a MVS PO (Partitioned Organised) data set.
Optional:

Name Physical

&SCLM_PROP_ELE_MemberDatasetName.(&SCLM_PROP_ELE_MemName.) The physical name of the PO member is specified by the current values of the two properties SCLM_PROP_ELE_MemberDatasetName and SCLM_PROP_ELE_MemName .