Tivoli Service Desk 6.0 Developer's Toolkit Interface Designer Guide

Chapter 3: Map Files and the EHLLAPI Map Utility

Back to Table of Contents


Introduction

Overview

The map files used by EHLLAPI are ASCII text files. There are two sections in a map file: the Header and the Field.

Header section

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:

Fields section

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.

System formats

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
  • DEFAULT_FORMAT means the string is right-aligned and padded with blanks.
  • LEFT_JUSTIFY means the string is left-aligned and padded with blanks.
  • ZERO_PAD means the string is padded with zeros instead of padded with blanks.
INTEGER
  • DEFAULT_FORMAT is where the integer is prefixed with the sign only if negative, right-aligned, padded with blanks, and base 10 (decimal).
  • LEFT_JUSTIFY means the integer is left-aligned.
  • ZERO_PAD means the integer is padded with zeros.
  • PREPEND_SIGN means the integer is prefixed with the sign, no matter whether it is positive or negative.
  • RADIX_16 means the integer is base 16 (hexadecimal).
  • GROUP_BY_3 means the integer is separated into groups of three (thousands) by a comma, unless another separator is specified For example, 1000000 would be 1,000,000.
  • GROUP_SEPR_DOT means the separator used with theGROUP_BY_3 format is a period.
  • GROUP_SEPR_SPACE means the separator used with the
  • GROUP_BY_3 means the format is a space.
BOOLEAN
  • DEFAULT_FORMAT means the value is shown as TRUE/FALSE, right-aligned.
  • LEFT_JUSTIFY means the value is left-aligned.
  • YES_NO means the value is shown as YES/NO.
  • 1_0 means the value is shown as 1/0.
REAL
  • DEFAULT_FORMAT means the number is right-aligned, padded with blanks, has no grouping, has a decimal place held by a period, and a sign is prefixed only if the number is negative.
  • LEFT_JUSTIFY means the number is left-aligned.
  • ZERO_PAD means the number is zero padded.
  • PREPEND_SIGN means the number is prefixed with a sign, no matter whether it is positive or negative.
  • DECIMAL_COMMA means the decimal place is held by a comma.
  • GROUP_BY_3 means the number is separated into groups of three (thousands) by a comma, unless another separator is specified. For example, 1000000.00 would be 1,000,000.00.
  • GROUP_SEPR_DOT means the separator to be used with the GROUP_BY_3 format is a period.
  • GROUP_SEPR_SPACE means the separator used with the GROUP_BY_3 format is a space.
TIME
  • DEFAULT_FORMAT means the value is shown right-aligned, padded with blanks, with seconds, in 24-hour format.
  • LEFT_JUSTIFY means the value is left-aligned.
  • ZERO_PAD means the value is padded with zeros.
  • WITHOUT_SECONDS means the value is only shown with hours and minutes.
  • AM_PM means the value is shown in 12-hour format, with A.M. or P.M. following.
DATE
  • DEFAULT_FORMAT means the value is shown right-aligned, padded with blanks, U.S. format, has slash separators, with a full year (includes century, for example: 1999), numeric months.
  • LEFT_JUSTIFY means the value is left-aligned.
  • ZERO_PAD means the value is padded with zeros.
  • EUROPEAN_FORMAT means the value is shown as day/month/year.
  • YMD_FORMAT means the value is shown as year/month/day.
  • DASH_SEPARATORS means separators are dashes ("--").
  • NO_SEPARATORS means the value is shown with no separators.
  • TRUNCATE_CENTURY means the year contains only the last two digits (assumes 19 for century).
  • NAMED_MONTHS means the value is shown with the appropriate name for the month. For example, January 1, 1999.
  • SHORT_NAMES means the month names are abbreviated. For example, Jan. 1, 1999.
  • ALL_CAPS means the month name is shown capitalized For example, January 1, 1999 or JAN 1, 1999.

User-defined format functions

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
  • Download means the sourcetype must always be STRING.
  • Upload means the sourcetype must match the type of the TSD Script variable or record field being translated.
targettype
  • Download means the targettype must match the type of the TSD Script variable or record field being translated.
  • Upload means the targettype must always be STRING.
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

EHLLAPI Map Utility Operation

Introduction

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.

What is the 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.

Start-up

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:

  1. Go to the directory where you installed the EHLLAPI Map Utility (the directory contains the maputil.kb file).
  2. Parse maputil.kb.
  3. At the command line, type the following:
    KML MAPUTIL
  4. Press ENTER.
    Result: An empty, scrollable TSD Developer's Toolkit - EHLLAPI Map Utility window appears.

Special characters

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.

Capturing a host screen

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:

  1. Use your terminal emulation session to get to the host screen you wish to capture.
  2. From the EHLLAPI Map Utility's File menu, choose Capture Host Screen.
    Result: You are prompted for a file name.
  3. Type a valid file name in the entry box.
    Result: You are prompted for the terminal session (short name) to use.
  4. Choose OK.
    Result: The screen is captured, saved, and appears in the TSD Developer's Toolkit-EHLLAPI Map Utility window

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.

Loading a screen file

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:

Creating map entries

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:

  1. Place the mouse pointer on the left edge of the first position of the field.
  2. Drag the pointer to the end of the field, then release the mouse button.
    Result: The selected area is highlighted in your system's highlight colors.

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:

  1. From the Map menu, choose Create Entry (or press INSERT).
    Result: A dialog box appears.
  2. Complete the information in the text boxes.
  3. Choose OK.
    Result: The highlighted field becomes the active object. The active object is presented in the system active title text and active title text background.

Editing map entries

To edit a map entry:

  1. Choose the map entry by clicking it.
    Result: The map entry becomes the active object.
  2. From the Map menu, choose Edit Entry.
    Result: A dialog box appears that allows you to change the settings for the map entry.
  3. Make any necessary changes.
  4. Choose OK.

Note: Double-clicking an object is equivalent to clicking it once and choosing Edit Entry.

Deleting map entries

To delete a map entry:

  1. Choose the entry by clicking it.
    Result: The entry becomes the active object.
  2. Press DELETE.

Setting map header attributes

To set the header information for the map file:

Saving a map file

To save an unnamed map file (or if you wish to save the file with a different name):

  1. From the File menu, choose Map Save As.
    Result: A File Name dialog box appears.
  2. In the text box, type the file name.
  3. Choose OK.

If you wish to save a map that is already named:

Applying a map file

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:

  1. From the Map menu, choose Apply Map.
    Result: A dialog box appears that asks for the name of the map file.
  2. In the text box, type the name of the map file.
  3. Choose OK.

After the map is applied, you can edit, delete, and add entries to the map.

Resetting the EHLLAPI Map Utility

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:

Setting EHLLAPI Map Utility fonts

To change the font used on the utility window:

Note: The font setting is not saved when you close the EHLLAPI Map Utility.

Exiting the EHLLAPI Map Utility

You may exit the EHLLAPI Map Utility's execution using one of the following methods:

  1. From the File menu, choose Exit.
  2. Double-click the window's system menu.
  3. From the window's system menu, choose Close.

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.

EHLLAPI Map Utility Example

AS/400 screen example

For this example, an AS/400 screen is shown that displays network attributes. In the course of the example, you:

  1. Capture the screen.
  2. Create a map.
  3. Write the code segment necessary to perform a download from the screen.

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

Starting the EHLLAPI Map Utility

To use the EHLLAPI Map Utility example follow these steps:

  1. Start the EHLLAPI Map Utility.
  2. Start a Communications Manager terminal emulation session (this one is named session "A").
  3. Log on and issue the commands to display AS/400 net attributes.

Creating a map with the EHLLAPI Map Utility

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

Creating a map entry for network IDs

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

Back to Table of Contents

Copyright