Metadata
| Access |
 ARCAD-API Server →  Metadata Designer |
The 5250 flow does not contain any functional information about what is displayed on screen. It only contains information about what must be displayed and how it must be displayed (character, display attributes, etc.). APIs must be able to interpret data displayed on the 5250 screen. To do this, you must assign IDs to the areas on your screen that contain data that the web service needs to interpret.
ARCAD-API allows you to assign functional attributes to specific areas in the 5250 screen. A screen area is a rectangle drawn on screen that delimits the portion of text to identify. This means that you can select a certain area in the emulator, that corresponds to a field in your application, and attribute an ID. These IDs are called metadata. Metadata identify one or more screen area(s).
Metadata IDs are used when designing scenarios for your web service. When a web service calls a metadata ID, the data contained in the related screen area(s) can be extracted from the 5252-flow and interpreted or manipulated if there are values to input in a given field.
The Customer ID in your application is displayed on line 4, columns 5 to 10 of a given screen. The only information you can get at the 5250 flow level is the character sequence and the related display attributes. You need to create an ID that allows you to know where the Customer ID is found in your emulator on each given screen.
To assign a functional ID to an area of a screen, use the metadata designer to draw a rectangle around the area and assign a metadata ID.
Two different users can run the same scenario using two different user accounts because the user and password fields are metadata. When executing the scenario via the web service, they each enter their own user/password and, via the metadata ID's, the system automatically replaces the scenario's values with the input values.
ARCAD-API can assign different types of metadata:
- screens: a screen ID is created by one or more screen areas that allow you to identify a unique screen. The combination of the areas defined for a screen ID and their relative positions must be unique for each screen. This means that this combination of areas can only be found on this screen. The screen ID is important because it is the parent ID for all other metadata.
- fields: a field ID defines a specific screen area that contains individual data.
- lists: a list ID defines a portion of the screen that is used to display a list of items as a table. A list's area must cover the entire portion of screen that is used to display the elements of the table.
- columns in lists: a column ID defines the area that covers one column in a list. The column's area must be included in the area covered by the parent list ID.
- end of list messages: an end of list ID defines the portion of the screen where a message appears when the end of the list is reached. The text value that will be displayed when the end of the list has been reached while browsing the entire element of the table may not be found on the same screen as the parent list if the list flows over multiple screens.
The metadata designer allows you to assign IDs in advance. Pre-defined metadata are available in the scenario designer. Metadata can also be created while you are recording scenarios in the scenario designer, however creating them in advance via the simplified metadata designer may save you time. There is also a possibility to duplicate metadata that are reused from on screen to another.
The F2, F5 and F12 keys can be used inside the emulator because they have been removed from the standard key binding context.
Accessing the Metadata Designer
The Metadata Designer is accessed directly from the navigator. There is only one screen for this designer which you use to access any of the IBM i connections available.
The designer must connect to an IBM i server, therefore at least one target 5250 session connection must already be defined.
To connect to the IBM i on which to capture the metadata, select the partition connection from the Target Configuration drop-down list. This list is pre-populated with all of the 5250 Session Configurations that are already defined. The connection is established automatically. The first screen in the 5250 will appear if the connection is successful.
If a connection cannot be made, the screen will remain black. Make sure that your local machine and user have access to the target server in the 5250 Configuration editor.
To 
disconnect and 
reconnect to any partition, click the corresponding icon(s).
For more information about creating IBM i connections to use in the metadata designer, refer to IBM i connections.
Creating metadata
Metadata is captured by drawing a parameter around specific screen areas in the 5250 interface using your mouse. Drag your cursor to define a parameter around a field in which you either enter text or in which text is automatically displayed, or around whole lists to capture all of their contents.
The metadata designer displays a 5250 emulator on which you can navigate through your application. Navigate "as usual", using your keyboard, through your application to reach the screens that contain the data to identify. To navigate in your application, you must be in 
Record Mode.
Once you have reached a screen to identify, switch to the mode that corresponds to the type of metadata you wish you identify. After you have identified everything you need on one screen, toggle back to record mode to continue the navigation. The process continues as such, going back and forth between entering commands to navigate the 5250 interface and then creating metadata IDs.
You must always remember to click back on the Toggle to Record Mode when you are finished creating the metadata and are ready to navigate in the interface again. If you are not in record mode, you will not be able to enter commands and navigate because the system believes you are still drawing perimeters to define metadata IDs.
When you are defining metadata in the designer, you are not recording a scenario. Your movements and the commands you enter are not recorded. In this view the "record mode" is for working in the 5250 interface and the metadata modes are for drawing the parameters to capture information.
Once they are created, if the metadata do not appear automatically, click on the 
Refresh Metadata icon to update the designer.
Follow the subsequent steps to create the metadata that you will use, and reuse often, throughout the scenarios in your web service.
Step 1 Select the Target Configuration.
At first, the designer is automatically in Record Mode and the system is ready for you to navigate through the 5250 emulator.
In record mode, the screen ID displayed in the metadata area always corresponds to the last screen that contained defined data, not necessarily the current screen. If there is no data defined for the current screen, especially no screen ID, the ID field will not reflect the current state of what is showing on-screen.
Step 2 Use your keyboard to log in and enter commands as necessary to navigate through your application and access the various screens that contain the metadata you require.
Step 3 When you have reached a screen that contains data to identify, click the icon that corresponds to the type of metadata to define the various metadata. The specific information about defining the different types of metadata are described below:
When creating a new ID, ARCAD-API verifies that there are no existing IDs that already cover the area selected. You cannot create two overlapping metadata. The data on screen can always only belong to one defined metadata ID.
Step 4 Toggle back to the Record Mode to navigate your application and capture the metadata on different screens.
Step 5 Repeat steps 2 through 4 as many times as you need to define all of the metadata in your application.
Step 6 Click Disconnect to sign off from the Target Configuration.
Define screen IDs
Screen metadata is used to define individual, unique screens. Screen IDs are important to identify because they are the parent element for any other metadata defined on the screen. The screen ID is associated with all of the fields and/or lists so that each metadata is truly unique. The data must conform to the information defined in the metadata and to the parent screen ID to be valid.
A screen can be defined by one or multiple fields. If a screen can be considered unique using only one field of information, such as the screen's title, then it is recommended that only the one area be used. However, if you have multiple screens in your application with the same title, each screen can use the title as an ID key as well as any number of other identifying fields on the screen, such as a list name. If there are multiple areas that make up a screen ID, they must all be satisfied before searching for the child metadata because all of the areas together make up the "uniqueness" factor for the screen ID.
Follow the subsequent steps to create screen ID metadata.
Step 1 Navigate to the desired screen using the Record Mode.
Step 2 Click the Screen ID icon to switch to the mode that allows you to draw the perimeter around the areas that define the screen.
Step 3 Select the area of the screen you want to use as an identifier. Use your mouse to draw a box around the area.
To use multiple areas on the screen to define the screen, press and hold the SHIFT key while you draw multiple boxes.
Step 4 Enter the ID name for the screen in the dialog that appears.
Step 5 Click OK to save.
Result The screen ID is created and appears in the Screen Metadata section. The range of the screen area selected is displayed as well as the name of the metadata ID. The perimeter around the screen area selected for the metadata ID is highlighted.
Step 6 Toggle back to the Record Mode to continue navigating.
If you remain in the Screen ID mode and continue to click in the emulator, the system considers that you are redefining the screen ID's perimeter. The new range for the ID will replace the original range. To avoid this, it is best to habitually toggle back to record mode as soon as you have created an ID.
If you do replace the original range for the ID, you can simply redraw the perimeter as required.
Define field IDs
Field metadata IDs define the scope of one field. You can create any number of field metadata on each screen. The only constraint is that the perimeter for each field is unique.
You cannot create two IDs for the same area on a screen and you cannot create two IDs with the same name on the same screen. Two field IDs can have the same name as long as they are found on different screens.
Follow the subsequent steps to create field ID metadata.
Step 1 Navigate to the desired screen using the Record Mode.
Step 2 Click the Field ID icon to switch to the mode that allows you to draw the perimeter around the area that defines the field.
Step 3 Select the area of the screen you want to use as an identifier. Use your mouse to draw a box around the area.
Step 4 Enter the ID name and a description for the field in the dialog that appears.
Step 5 Select the Data Type in the drop-down list. The data type can be Alpha, Integer, Boolean, Float, Date. For date data types, enter a Date Format in the field.
If the field is a password, be sure to tick the Is password checkbox in the Field Definition dialog. While executing a web service that involves a password field, its content will not be displayed in the log file. Anonymous stars will be displayed, instead, protecting your identifying data.
Step 6 Click OK to save.
Result The field ID is created and appears in the Screen Metadata section. The range of the area selected is displayed as well as the name and type of the metadata ID. When you select an ID, the perimeter around the screen area selected is highlighted and the name of the ID is displayed.
Step 7 Toggle back to the Record Mode to continue navigating.
Define list IDs
List metadata is used to define the entire area in which a list is and could be displayed. List IDs are important to identify because they are the parent element for any column or end of list metadata.
Follow the subsequent steps to create list ID metadata.
Step 1 Navigate to the desired screen using the Record Mode.
Step 2 Click the List ID icon to switch to the mode that allows you to draw the perimeter around the entire area of the list.
Step 3 Select the area of the screen you want to use as an identifier. Use your mouse to draw a box around the area.
For lists, the screen area must cover the whole list, even if there are not currently enough entries to go all the way to the bottom of the page. Ensure that all the lines and columns that could potentially display an item in the list are included in the selected area.
Step 4 Enter the ID name for the list in the dialog that appears.
Step 5 Click OK to save.
Result The list ID is created and appears in the Screen Metadata section. The range of the area selected is displayed.
Step 6 Toggle back to the Record Mode to continue navigating.
Define column IDs
Column metadata is used to define specific columns in lists. Each column ID must be part of a parent list.
Follow the subsequent steps to create column ID metadata.
Step 1 Navigate to the desired screen using the Record Mode.
Step 2 Click the Column ID icon to switch to the mode that allows you to draw the perimeter around a column in a list.
Step 3 Select the area of the screen you want to use as an identifier. Use your mouse to draw a box around the area.
For columns, the screen area must cover the whole column, even if there are not currently enough entries to go all the way to the bottom of the page. Ensure that all the lines that could potentially display a list item are included in the selected area.
The perimeter drawn for a column must be inside the perimeter of the parent list. The perimeter of the list is displayed on screen to guide you.
If the column is outside of the parent list, an error is displayed and you must draw the perimeter again.
If there is no parent list ID, create it first.
Step 4 Enter the ID name and a description for the column in the dialog that appears.
Step 5 Click OK to save.
Result The column ID is created and appears in the Screen Metadata section as part of the parent list's details.
Step 6 Toggle back to the Record Mode to continue navigating.
Define end of list IDs
The 
end-of-list ID is attributed to the area where a predefined message will appear once the end of the list is reached.
Follow the subsequent steps to create end-of-list ID metadata.
Step 1 Navigate to the desired screen using the Record Mode.
Step 2 Click the End of List ID icon to switch to the mode that allows you to draw the perimeter around the message at the end of a list.
Step 3 Select the area of the screen you want to use as an identifier. Use your mouse to draw a box around the area.
The end of list ID must correspond to a parent list. If there is no parent list ID, create it first.
Step 4 Enter the ID name for the message in the dialog that appears.
Step 5 Click OK to save.
Result The end-of-list ID is created and appears in the Screen Metadata section. The range of the area selected is displayed.
Step 6 Toggle back to the Record Mode to continue navigating.
It is possible to reach the end of a list without defining a End of Line message.
If no End Of Line Message has been defined, ARCAD API compares the existing list content with the previous one and considers that the end of list has been reached if the current list content is the same as the previous one.
Navigating through multi-page data
To take into account columns containing hidden data in other parts of the emulator, you can scroll horizontally through columns. Select the wanted navigation mode when defining the columns in the Metadata Designer view, and then navigate horizontally on the IBM i emulator.
There are two navigation modes available:
- Axial: this navigation mode contains two navigation keys, the
Previous Page button and the 
Next Page button. With these two keys, you can move left and right on the emulator. - Circular: this navigation mode contains only one navigation key, the Next page button. Once the emulator reaches the last page, the next time you press the Next Page button, it takes you back to the initial page.
Make sure that you have defined your list ID beforehand.
For more information about the list ID definition, refer toDefine list IDs.
Follow the subsequent steps to set the horizontal navigation.
Step 1 In the Screen Metadata section of the MetaData Designer view, click on the Toggle to Screen Columns definition mode icon.
Step 2 In the Navigation Type option, select one of the two navigation modes available in the drop-down list.
Step 3 In the Previous Page and Next Page options, select the emulator keys available in the drop-down list.
After defining the navigation option and navigation keys, you can create new columns. Select the area of the screen you want to use as an identifier. Use your mouse to draw a box around the area.
Result The horizontal navigation is set and can be used to display hidden data columns.
Setting metadata columns
For already existing columns, it is possible to edit their page number, as well as the navigation mode and navigation keys.
If you enter a page number that does not correspond to a column, the web services using this column, either as input or as output, return an execution error.
Follow the subsequent steps to edit existing columns.
Step 1 In the Screen Metadata section of the MetaData Designer view, click on the Toggle to Screen Columns definition mode icon.
Step 2 Double-click on an existing column to open the Column Definition dialog.
Step 3 Tick the Set Metadata Column option to be able to set the Column Page option.
A confirmation dialog opens.
Click OK to confirm or click Cancel to close the dialog.
Step 4 Set the Column Page option. The value is an integer.
Step 5 Select the Navigation Type option, as well as the emulator navigation keys in the Previous Button and Next Button options.
Click OK.
Result The construction and execution of a web service can now take into account hidden columns.
Duplicating metadata
You can 
duplicate the metadata that are reused from one screen to another. Transferring metadata from another screen allows to save time on similar screens/scenarios.
Step 1 Navigate to the desired screen using the Record Mode. Click the Duplicate icon.
Step 2 Select the metadata you want to duplicated in the dialog that appears.
Step 3 Enter a new Screen Identifier for the metadata. The same name is attributed by default.
Step 4 Click OK.
Deleting metadata
To delete an entry, find it in its parent tab (Screen ID, Fields, or Lists), right-click on it and then select 
Delete. To find the correct data in the tab, you must first navigate to the parent screen using the Record Mode.
