Tivoli Service Desk 6.0 Developer's Toolkit Interface Designer Guide
The map files used by EHLLAPI are ASCII text files. There are two sections in a map file: the Header and the Field.
Header information contains attributes that are global to a map file. For instance, you may want the TSD Script Interpreter to press ERASE_EOF before filling in each field.
The format for a header is as follows:
*HEADER CLEAR_FIRST = {{TRUE or ON}|{FALSE or OFF}} MOVE_CURSOR = {{TRUE or ON}|{FALSE or OFF}} LIBRARY = {kbc library to use as the default for user- defined format functions}
The header should always be the first section of the map file. The specifications are as follows:
This section specifies the host fields and their relationship to TSD Script data. Essentially, each line of the fields section links one host data field position to one TSD Script record field. Alternatively, if the data to be transferred is a single TSD Script variable, then one line in the field section links the host data field position with that TSD Script variable name. Each line of the fields section is called a map entry.
The format of the fields section for a map file is as follows:
*FIELDS {field}[, ]{row}[, ]{{col}[, ]{{len} {{USERFORMAT [, ]{[file:]routinename}|{SYSFORMAT[, ]{constant [constant ...]}}
Each segment of a map entry must be separated by white space (one or more blanks or tabs), or by a comma. Each segment is described below:
Each host data field must be translated either to or from a TSD Script type.
For each TSD Script simple field type, certain system formats apply to the types.
System formats may be combined to list more than one system format for a field. If you have a string that you want left-aligned and padded with zeros when you upload it, you could write some TSD Script code to do it, or you could specify LEFT_JUSTIFY ZERO_PAD as the system format in the map file. Using the system format is easier and it executes faster than a TSD Script conversion routine. Unless you must write a special TSD Script conversion routine, you should use the system format.
The application of a system format depends on the TSD Script simple type being formatted. The TSD Script simple types, applicable system formats, and associated descriptions follow.
Type | Description |
STRING |
|
INTEGER |
|
BOOLEAN |
|
REAL |
|
TIME |
|
DATE |
|
In some circumstances, you may want to write your own format functions in TSD Script. A user-defined format function accepts input data, converts it to the new format, and returns a Boolean indicating the success of the operation. The prototype for user-defined format functions is:
FUNCTION {funcname}(VAL {source}:{sourcetype}, REF {target}:{targettype}):BOOLEAN
Explanations of user-defined format functions follow:
User-Defined Format Function | Description |
sourcetype |
|
targettype |
|
returntype | The return type must be BOOLEAN. If the function returns FALSE, then the TSD Script Interpreter assumes that an error occurred, and returns EMUERR_FORMAT_FN_FAILURE (-7005) to the caller. If the translate function returns TRUE but sets the target value to $Unknown, the TSD Script Interpreter assumes successful conversion and carries out the operation. In the case of a download, the TSD Script variable or record field gets an $Unknown value. In the upload, the TSD Script Interpreter skips the field. |
Because the rules differ for types depending on the direction of data flow, a map that includes user functions must be dedicated to either upload or download unless both the target and source types are STRING.
As an example, suppose you want to convert an Tivoli Problem Management (TPM) severity code, which is numeric, to an alphabetic scale (for example, 1 to A, 2 to B, and so on). Additionally, during a download, you want to convert from the alphabetic scale back to the numeric. First, a TSD Script function is written to change the numeric to alphabetic (for upload):
FUNCTION ToAlpha(VAL inSeverity:INTEGER, REF outSeverity:STRING):BOOLEAN IS ACTIONS outSeverity := Char(64 + inSeverity); Exit(TRUE); END; -- ToAlpha
Next, a routine is created to convert the alphabetic back to numeric (for download):
FUNCTION ToNumeric(VAL inSeverity:STRING, REF outSeverity:INTEGER):BOOLEAN IS ACTIONS outSeverity := CharCode(StrUpper(inSeverity)) - 64; END; -- ToNumeric
Assume these functions are stored in a file named CONVERT. In the upload map field definition for severity, the ToAlpha function is specified as follows:
SEVERITY 10 10 1 USERFORMAT CONVERT:TOALPHA
In the download map field definition for severity, the ToNumeric function is specified as follows:
SEVERITY 10 10 1 USERFORMAT CONVERT:TONUMERIC
Although map files are simple, creating map files by hand for an entire interface application can be time-consuming.
Correctly determining host screen positions by counting rows and columns is prone to human error, especially when the developer is confronted with many screens each containing many fields.
Most interface developers would rather spend their time working out the logistics of the interface.
Modification of the map file at a later date (or by someone else) is difficult if the user has only the text file at which to look.
To overcome these concerns, Tivoli Systems created the EHLLAPI Map Utility.
The EHLLAPI Map Utility provides an intuitive way to create map files that are used by TSD Script EMUMapUpload and EMUMapDownload.
The EHLLAPI Map Utility allows you to capture host screens and store them as text files (SCR files). Map files, based on the captured screens, are created when fields for which you wish to create field entries are selected. To select field entries, you can click and drag on the fields.
Additionally, the EHLLAPI Map Utility is useful for interface maintenance because the tool loads SCR files (captured previously) and applies any map file to the screen. With the EHLLAPI Map Utility, field entries are created, viewed, edited, and deleted in a visual, intuitive way.
The EHLLAPI Map Utility is written entirely in TSD Script. If you wish to make modifications to the TSD Script code, Tivoli Systems recommends that you make a backup copy of the original code (maputil.kb, mapentry.df) before you begin.
In order to use the EHLLAPI Map Utility, you must have TSD Developer's Toolkit installed on your machine. In order to use the Capture option, you need to install the EHLLAPI Extensions for TSD Developer's Toolkit also.
To start the tool:
When you look at screens that have been captured from the host, you see characters that were not visible in the terminal window. These characters are hidden host characters which act as field delimiters. The EHLLAPI Map Utility does not strip these characters out, because they could be of assistance to you in determining where data fields begin and end.
The first operation with which you should familiarize yourself is capturing a host screen. This is a necessary first step in setting up an upload/download operation for any host screen.
When you capture a screen, it is:
Tivoli Systems adopted the convention of putting the extension .SCR on captured screen files; however, you may choose any extension you wish when naming the file.
To capture a host screen:
Note: After you capture a screen, the Capture Host Screen menu command becomes inactive.
If you wish to capture another host screen:
The EHLLAPI Map Utility window is resizable. If the host screen is not completely visible, you can resize the window until the entire screen is visible. You cannot make map entries for the areas outside the host screen if the window is too large.
Note: You use terminal emulation sessions only to capture screens. All other EHLLAPI Map Utility operations use only TSD Developer's Toolkit. This allows you to capture a number of screens at once, then make maps later, even if you use a machine that does not have Communications Manager.
If you wish to load a previously captured screen file:
After you load a screen file, the Load Screen File becomes inactive. If you wish to load another screen:
Once you load a screen file, you can create a map file for that screen.
To select the field for which a map entry is created:
If the pointer drags too quickly, the highlighted area may not include the first character of the field. If this occurs, repeat the steps above.
To create an entry for the highlighted area:
To edit a map entry:
Note: Double-clicking an object is equivalent to clicking it once and choosing Edit Entry.
To delete a map entry:
To set the header information for the map file:
To save an unnamed map file (or if you wish to save the file with a different name):
If you wish to save a map that is already named:
Applying a map file to a screen allows a user to read the specified map file and to highlight the map entries that are found in the map file. This is helpful when users need to add to or change a map file.
To apply a map file to a screen:
After the map is applied, you can edit, delete, and add entries to the map.
When you display a screen, or if you have a map applied to a screen, some File menu commands are unavailable. If you need to capture a new screen, or load a different screen file, you need to reset the current display.
To reset the current display:
To change the font used on the utility window:
Note: The font setting is not saved when you close the EHLLAPI Map Utility.
You may exit the EHLLAPI Map Utility's execution using one of the following methods:
If you choose to exit, but have not saved your latest changes, a message appears that asks if you want to save the file.
If you choose Yes and the file was not named, a File dialog box appears that allows you to name the file.
For this example, an AS/400 screen is shown that displays network attributes. In the course of the example, you:
The example files (named example.scr, example.kb and example.map) can be found in the OS2ASE directory.
The host screen looks like the following example:
Display Network Attributes System:
System:
S1028662
Current system name . . . . . . . . .. . . : S1028662
Pending system name . . . . . . . . . . . .:
Local network ID . . . . . . . . . . . . . : APPN
Local control point name . . . . . . . . . : S1028662
Default local location . . . . . . . . . . : S1028662
Default mode . . . . . . . . . . . . . . . : BLANK
APPN node type . . . . . . . . . . . . . . :*ENDNODE
Maximum number of intermediate sessions. . : 200
Route addition resistance . . . . . . . . .: 128
Server network ID/control point name .. . .:
More...
Press Enter to continue.
F3=Exit F12=Cancel
To use the EHLLAPI Map Utility example follow these steps:
Once you complete the procedures in the previous section, you can capture a screen.
Example.scr is chosen as the screen file name, although a real interface would probably use a more descriptive name like dnetattr.scr. Using the screen file name as a basis, you create a map named example.map.
To make this example simple and effective:
The following list details the information used for each map entry:
Map Entry | Description |
currentSystemName | Length 8, system format is DEFAULT_FORMAT, TSD Script type is STRING. |
pendingSystemName | Length 8, system format is DEFAULT_FORMAT, TSD Script type is STRING. |
localNetworkID | Length 8, system format is LEFT_JUSTIFY, TSD Script type is STRING. |
localCPName | Length 8, system format is DEFAULT_FORMAT, TSD Script type is STRING. |
dfltLocalLocation | Length 8, system format is DEFAULT_FORMAT, TSD Script type is STRING. |
dfltMode | Length 8, system format is LEFT_JUSTIFY. |
APPNNodeType | Length 8, system format is DEFAULT_FORMAT, TSD Script type is INTEGER. |
maxNbrIntSess | Length 4, system format is LEFT_JUSTIFY, TSD Script type is INTEGER. |
routeAddRes | Length 3, system format is LEFT_JUSTIFY, TSD Script type is INTEGER. |
These system formats (other than DEFAULT_FORMAT) are used by upload operations. For download operations, the white space is trimmed from the values. Header attributes are not set for this map; rather, the default settings are used.
After you create all entries, save the map as EXAMPLE.MAP. The EHLLAPI Map Utility generates a file that looks like the following example. This example performs a simple download. However, it illustrates the basic steps of map creation using the EHLLAPI Map Utility.
*REM Mapfile name is E:\EHLLAPI\MAPUTIL\example.map *HEADER CLEAR_FIRST = FALSE MOVE_CURSOR = TRUE
*FIELDS
currentSystemName, 3, 55, 8, SYSFORMAT, DEFAULT_FORMAT pendingSystemName, 4, 57, 8, SYSFORMAT, DEFAULT_FORMAT localNetworkID, 5, 55, 8, SYSFORMAT, LEFT_JUSTIFY localCPName, 6, 55, 8, SYSFORMAT, DEFAULT_FORMAT dfltLocalLocation, 7, 55, 8, SYSFORMAT, DEFAULT_FORMAT dfltMode, 8, 55, 8, SYSFORMAT, LEFT_JUSTIFY APPNNodeType, 9, 55, 8, SYSFORMAT, DEFAULT_FORMAT maxNbrIntSess, 10, 55, 4, SYSFORMAT, LEFT_JUSTIFY routeAddRes, 11, 55, 3, SYSFORMAT, LEFT_JUSTIFY The TSD Script code segment to use this map file would look like:
TYPES
NetAttrRec IS RECORD currentSystemName :STRING; pendingSystemName :STRING; localNetworkID :STRING; localCPName :STRING; dfltLocalLocation :STRING; dfltMode :STRING; APPNNodeType :STRING; maxNbrIntSess :INTEGER; routeAddRes :INTEGER; $myDnloadMap {'EXAMPLE.MAP'}:STRING; END; ROUTIINES FUNCTION GetNetAttributes(VAL conn:EMUCONNECTION, REF netAttr:NetAttrRec):INTEGER IS
-- Assumes you are already at the right screen.
VARIABLES rc :INTEGER; ACTIONS rc := EMUMapDownload(conn, netAttr.$myDnloadMap,netAttr); IF (rc < 1) THEN WinMessageBox($DESKTOP,'Error',$MBOK, 'Map dnload returns '& rc); END; Exit(rc); END; -- GetNetAttributes
In this section, you create a map entry for the Server network IDs. There are five fields that can contain a server network ID.
Dragging the pointer from the first character of the first field to the last character of the last field creates an entry called srvrNetworkID and is considered a multi-line field by the EHLLAPI Map Utility. A user format function is created called ParseSrvrNames.
The format function looks like the following:
FUNCTION ParseSrvrNames(VAL inStr:STRING, REF srvrNetworkID:LIST OF STRING):BOOLEAN IS VARIABLES temp :STRING; ACTIONS temp := StrTrim(StrLTrim(inStr)); -- get rid of blank fields WHILE (Known(temp)) DO ListInsert(srvrNetworkID, StrCopy(temp,1,8)); temp := StrDelete(temp,1,80); END; Exit(TRUE); END; -- ParseSrvrNames
You declare srvrNetworkID as a list of strings in the record:
NetAttrRec IS RECORD currentSystemName :STRING; pendingSystemName :STRING; localNetworkID :STRING; localCPName :STRING; dfltLocalLocation :STRING; dfltMode :STRING; APPNNodeType :STRING; maxNbrIntSess :INTEGER; routeAddRes :INTEGER; srvrNetworkID :LIST OF STRING; $myDnloadMap {'EXAMPLE.MAP'}:STRING; END;
When the download function runs, the list is updated with correct values. You may find that this method proves more flexible than calling EMUFillBuffer repetitively, or creating dummy fields in the TSD Script record to download all the fields in a map and then insert the values one at a time into the list.
Tivoli Service Desk 6.0 Developer's Toolkit Legacy APIs Guide