Tivoli 服务台 6.0 开发工具包接口设计器指南

第 3 章:映射文件和 EHLLAPI 映射公用程序

返回目录


简介

概述

EHLLAPI 使用的映射文件是 ASCII 文本文件。映射文件中有两个部分:标题文件部分和字段部分。

标题部分

标题信息包含映射文件的全局属性。例如,在填写每个字段之前您可能希望 TSD 脚本解释器按 ERASE_EOF。

标题的格式如下所示:

*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}

标题始终应是映射文件的第一部分。其规范如下所示:

字段部分

此部分指定主机字段及其与 TSD 脚本数据的关系。实质上,字段部分的每行将一个主机数据字段位置与一个 TSD 脚本记录字段链接。或者是这样:如果要传送的数据是单个 TSD 脚本变量,则此字段部分中的一行与具有此 TSD 脚本变量名称的主机数据字段位置链接。字段部分中的每一行称为一个映射条目。

映射文件中字段部分的格式如下所示:

*FIELDS
{field}[, ]{row}[, ]{{col}[, ]{{len} {{USERFORMAT
[, ]{[file:]routinename}|{SYSFORMAT[, ]{constant [constant
...]}}

必须用空格(一个或多个空格或跳格设定)或逗号将映射条目的每个段分隔开。下面是对每个段的说明:

每个主机数据字段和 TSD 脚本类型之间必须可以相互转换。

系统格式

对于每个 TSD 脚本简单字段类型,采用一定的系统格式。

可能将系统格式组合起来,以列出字段的多个系统格式。当上载某个字符串时,如果希望向左对齐且用零填充,则可编写一些 TSD 脚本代码来完成此操作,或可指定 LEFT_JUSTIFY ZERO_PAD 作为映射文件的系统格式。系统格式更易于使用,且它的执行速度比 TSD 脚本转换例行程序的速度快。除非必须编写特定 TSD 脚本转换例行程序,否则,应使用系统格式。

系统格式的应用程序由正在格式化的 TSD 脚本简单类型决定。下面列出了 TSD 脚本简单类型、适用的系统格式和相关说明。

类型 说明
STRING
  • DEFAULT_FORMAT 指示此字符串将向右对齐并用空格填充。
  • LEFT_JUSTIFY 指示此字符串将向左对齐并用空格填充。
  • ZERO_PAD 指示此字符串用零(而非空格)填充。
INTEGER
  • DEFAULT_FORMAT 表示仅当整数为负数时才加符号前缀,且向右对齐,用空格填充,基数为 10(即十进制数)。
  • LEFT_JUSTIFY 指示整数采用向左对齐的格式。
  • ZERO_PAD 指示整数采用用零填充的格式。
  • PREPEND_SIGN 指示不论整数为正数还是负数,都要加符号前缀。
  • RADIX_16 指示整数的基数是 16(即十六进制数)。
  • GROUP_BY_3 指示在未指定其它分隔符时,用逗号将整数分为含三位数字(以千为单位)的组。例如,1000000 可表示为 1,000,000。
  • GROUP_SEPR_DOT 指示 GROUP_BY_3 格式所用的分隔符是句点。
  • GROUP_SEPR_SPACE 指示
  • GROUP_BY_3 格式所用的分隔符是空格。
BOOLEAN
  • DEFAULT_FORMAT 指示值显示为 TRUE/FALSE,并向右对齐。
  • LEFT_JUSTIFY 指示将值左对齐。
  • YES_NO 指示值显示为 YES/NO。
  • 1_0 指示值显示为 1/0。
REAL
  • DEFAULT_FORMAT 指示将数值右对齐、用空格填充、不分组、用句点表示小数点,且仅当数值为负数时加符号前缀。
  • LEFT_JUSTIFY 指示将数值左对齐。
  • ZERO_PAD 指示用零填充数值。
  • PREPEND_SIGN 指示不论数值为正数还是负数,都要加符号前缀。
  • DECIMAL_COMMA 指示用逗号表示小数点。
  • GROUP_BY_3 指示在未指定其它分隔符时,用逗号将数值分为含三位数字(以千为单位)的组。例如,1000000.00 将表示为 1,000,000.00。
  • GROUP_SEPR_DOT 指示 GROUP_BY_3 格式所用的分隔符为句点。
  • GROUP_SEPR_SPACE 指示 GROUP_BY_3 格式所用的分隔符为空格。
TIME
  • DEFAULT_FORMAT 指示将值右对齐、用空格填充、以秒为最小显示单位并用 24 小时格式表示。
  • LEFT_JUSTIFY 指示将值左对齐。
  • ZERO_PAD 指示用零填充值。
  • WITHOUT_SECONDS 指示只用小时和分钟表示值。
  • AM_PM 指示用 12 小时的格式表示值,后跟 A.M. 或 P.M.。
DATE
  • DEFAULT_FORMAT 指示将值右对齐、用空格填充、采用美国格式、用斜杠作分隔符、采用包含世纪的“年”的完整格式(例如:1999)、用数字表示“月”。
  • LEFT_JUSTIFY 指示将值左对齐。
  • ZERO_PAD 指示用零填充值。
  • EUROPEAN_FORMAT 指示用日/月/年的格式显示值。
  • YMD_FORMAT 指示用年/月/日的格式显示值。
  • DASH_SEPARATORS 指示分隔符为破折号(“--”)。
  • NO_SEPARATORS 指示显示的值中不包含分隔符。
  • TRUNCATE_CENTURY 指示年只包含最后两位(假定 19 表示世纪)。
  • NAMED_MONTHS 指示用合适的月名称表示值。例如,January 1,1999(1999 年 1 月 1 日)。
  • SHORT_NAMES 指示月名称采用缩写形式。例如,Jan. 1,1999(1999 年 1 月 1 日)。
  • ALL_CAPS 指示月名称采用大写形式。例如,January 1,1999 或 JAN 1,1999(1999 年 1 月 1 日)。

用户定义的格式函数

在某些情况下,可能希望在 TSD 脚本中编写您自己的格式函数。用户定义的格式函数接受输入数据,将数据转换为新格式,然后返回 Boolean 值以指示所做的操作是否成功。用户定义的格式函数的原型为:

FUNCTION {funcname}(VAL {source}:{sourcetype}, REF
                  {target}:{targettype}):BOOLEAN

下面是对用户定义的格式函数的说明:

用户定义的格式函数 说明
sourcetype
  • 下载指示源类型必须始终是 STRING。
  • 上载指示源类型必须与正在转换的 TSD 脚本变量或记录字段的类型匹配。
targettype
  • 下载指示目标类型必须与正在转换的 TSD 脚本变量或记录字段的类型匹配。
  • 上载指示目标类型必须始终是 STRING。
returntype 返回类型必须是 BOOLEAN。如果此函数返回 FALSE,则 TSD 脚本解释器假定遇到了错误,并向调用者返回 EMUERR_FORMAT_FN_FAILURE(-7005)。如果转换函数返回 TRUE 但目标值设置为 $Unknown,则 TSD 脚本解释器假定转换成功并执行此操作。在下载中,TSD 脚本变量或记录字段获得 $Unknown 值。在上载中,TSD 脚本解释器跳过此字段。

因为数据流的方向不同,类型的规则也不同,因此除了目标类型和源类型同为 STRING 的情况之外,包含用户函数的映射必须专用于上载或下载。

例如,假定希望将 Tivoli 问题管理(TPM)严重性代码(数字形式)转换为相应的字母形式(例如 1 变为 A、2 变为 B 等)。此外,在下载期间,希望将这些值从字母形式重新转换为数字形式。首先,编写一个 TSD 脚本函数来将数字形式变为字母形式(对于上载):

FUNCTION ToAlpha(VAL inSeverity:INTEGER, REF
                 outSeverity:STRING):BOOLEAN IS
ACTIONS
outSeverity := Char(64 + inSeverity);
                Exit(TRUE);
END; -- ToAlpha

其次,创建一个例行程序,以将字母形式重新转换为数字形式(对于下载):

FUNCTION ToNumeric(VAL inSeverity:STRING, REF
                  outSeverity:INTEGER):BOOLEAN IS
ACTIONS
outSeverity := CharCode(StrUpper(inSeverity)) - 64;
END; -- ToNumeric

假定这些函数保存在名为 CONVERT 的文件中。在对上载映射字段严重性的定义中,指定 ToAlpha 函数如下:

SEVERITY 10 10 1 USERFORMAT CONVERT:TOALPHA

在对下载映射字段严重性的定义中,指定 ToNumeric 函数如下:

SEVERITY 10 10 1 USERFORMAT CONVERT:TONUMERIC

EHLLAPI 映射公用程序操作

简介

尽管映射文件很简单,但是手动创建整个接口应用程序的映射文件可能很费时间。

通过对行和列进行计数以正确确定主机屏幕位置很容易造成人为的错误,特别是当开发人员面对许多屏幕且每个屏幕包含许多字段时,更是如此。

大多数接口开发人员宁愿花时间解决接口的数理逻辑问题。

如果用户只有可查看的文本文件,则在以后的某个日期对映射文件进行修改(或由别的人来修改)是很困难的。

为了解决上述问题,Tivoli Systems 创建了 EHLLAPI 映射公用程序。

映射公用程序的内容

EHLLAPI 映射公用程序提供创建映射文件的直观方法,这些文件由 TSD 脚本 EMUMapUploadEMUMapDownload 所使用。

EHLLAPI 映射公用程序使您能捕捉主机屏幕并将其保存为文本文件(SCR 文件)。当选择希望为其创建字段条目的字段时,根据捕捉到的屏幕创建映射文件。可通过单击并拖动字段来选择字段条目。

此外,EHLLAPI 映射公用程序对接口维护很有用,这是因为此工具可装入以前捕捉到的 SCR 文件并使任意映射文件应用于屏幕。有了 EHLLAPI 映射公用程序,就可以以直观形象的方式创建、查看、编辑和删除字段条目。

EHLLAPI 映射公用程序都是在 TSD 脚本中编写的。如果希望修改 TSD 脚本代码,则 Tivoli Systems 建议在开始修改前对原始代码(maputil.kb、mapentry.df)做备份。

启动

为了使用 EHLLAPI 映射公用程序,必须在机器上安装 TSD 开发工具包。而只有安装了 TSD 开发工具包的 EHLLAPI 扩展,才能使用“捕捉”选项。

要启动此工具:

  1. 转到安装了 EHLLAPI 映射公用程序的目录(此目录包含 maputil.kb 文件)。
  2. 分析 maputil.kb。
  3. 在命令行,输入下列命令:
    KML MAPUTIL
  4. 按 ENTER。
    结果:出现一个空的、可滚动的 TSD 开发工具包 - EHLLAPI 映射公用程序窗口。

特殊字符

查看从主机捕捉到的屏幕时,会看到一些在终端窗口看不到的字符。这些字符是隐藏的主机字符,作为字段定界符使用。因为这些字符有助于确定字段的开头和结尾,因此 EHLLAPI 映射公用程序不剔除这些字符。

捕捉主机屏幕

您自己应该熟悉的第一个操作是捕捉主机屏幕。首先为任意主机屏幕设置上载/下载操作很有必要。

捕捉屏幕时,进行了下列操作:

Tivoli Systems 约定捕捉的屏幕文件的扩展名为 .SCR,但是您在命名此文件时可以选择希望使用的任意扩展名。

要捕捉主机屏幕:

  1. 使用终端仿真会话,以获得希望捕捉的主机屏幕。
  2. 从 EHLLAPI 映射公用程序的“文件”菜单中选择“捕捉主机屏幕”。
    结果:提示输入文件名。
  3. 在条目框中输入有效的文件名。
    结果:提示输入要使用的终端会话的短名称。
  4. 选择“确认”。
    结果:捕捉、保存此屏幕,并在 TSD 开发工具包 - EHLLAPI 映射公用程序窗口中显示它

注:捕捉屏幕后,“捕捉主机屏幕”菜单命令变为不活动状态。

如果希望捕捉另一个主机屏幕:

EHLLAPI 映射公用程序窗口可改变大小。如果有部分主机屏幕不可见,则可改变窗口的大小直到整个屏幕都是可见的。如果窗口太大,则不能为主机屏幕以外的区域创建映射条目。

注:只能使用终端仿真会话来捕捉屏幕。所有其他 EHLLAPI 映射公用程序操作只能使用 TSD 开发工具包。这样,即使使用没有安装通信管理器的机器,也可以一次捕捉许多屏幕,以后再创建映射。

装入屏幕文件

如果希望装入以前捕捉到的屏幕文件:

装入屏幕文件后,“装入屏幕文件”变为不活动的。如果希望装入另一个屏幕:

创建映射条目

装入屏幕文件后,就可为此屏幕创建映射文件。

要选择为其创建映射条目的字段:

  1. 将鼠标指针置于此字段开头的左边缘。
  2. 拖动指针到此字段的结尾,然后释放鼠标按纽。
    结果:所选区域呈高亮显示(以系统的高亮色显示)。

如果指针拖动太快,则高亮区域可能不包括此字段的第一个字符。如果出现这样的情况,则重复以上步骤。

要为高亮区域创建条目:

  1. 从“映射”菜单中选择“创建条目”(或按 INSERT)。
    结果:出现一个对话框。
  2. 完成文本框中的信息输入。
  3. 选择“确认”。
    结果:高亮字段变为活动对象。在系统活动标题文本和活动标题文本背景中出现此活动对象。

编辑映射条目

要编辑映射条目:

  1. 通过单击选择映射条目。
    结果:映射条目变为活动对象。
  2. 从“映射”菜单中选择“编辑条目”。
    结果:出现一个对话框,使您能更改此映射条目的设置。
  3. 进行任何必需的更改。
  4. 选择“确认”。

注:双击对象与单击它再选择“编辑条目”等价。

删除映射条目

要删除映射条目:

  1. 通过单击选择此条目。
    结果:此条目变为活动对象。
  2. 按 DELETE。

设置映射标题属性

要设置此映射文件的标题信息:

保存映射文件

要保存未命名的映射文件(或如果想用不同的名称来保存此文件):

  1. 从“文件”菜单中选择“映射另存为”。
    结果:出现一个文件名对话框。
  2. 在文本框中输入文件名。
  3. 选择“确认”。

如果要保存已命名的映射:

应用映射文件

将映射文件应用到屏幕,可使用户读取指定的映射文件并高亮显示在此映射文件中找到的映射条目。当用户需要添加或更改映射文件时,这很有用。

要将映射文件应用到屏幕:

  1. 从“映射”菜单中选择“应用映射”。
    结果:出现一个对话框,询问映射文件的名称。
  2. 在文本框中输入映射文件的名称。
  3. 选择“确认”。

应用映射后,可编辑、删除映射中的条目以及向映射添加条目。

使 EHLLAPI 映射公用程序复位

显示屏幕时,或如果将映射应用到屏幕,可能不能使用一些“文件”菜单命令。如果需要捕捉新屏幕或装入不同的屏幕文件,则需要使当前显示器复位。

要使当前显示器复位:

设置 EHLLAPI 映射公用程序字体

要更改公用程序窗口所用的字体:

注:当关闭 EHLLAPI 映射公用程序时,不保存字体设置。

退出 EHLLAPI 映射公用程序

可使用下列方法之一退出 EHLLAPI 映射公用程序的执行:

  1. 从“文件”菜单中选择“退出”。
  2. 双击窗口的系统菜单。
  3. 从窗口的系统菜单中选择“关闭”。

如果选择退出但未保存最近的更改,则出现一条消息,询问是否要保存此文件。

如果选择“是”且文件未命名,则出现一个文件对话框,使您能命名此文件。

EHLLAPI 映射公用程序实例

AS/400 屏幕实例

此例显示列出网络属性信息的 AS/400 屏幕。在此例中,您:

  1. 捕捉屏幕。
  2. 创建映射。
  3. 编写从屏幕下载所需的代码段。

可在 OS2ASE 目录中找到这些实例文件(名为 example.scr、example.kb 和 example.map)。

主机屏幕与下列实例相似:

显示网络属性系统:

系统:
S1028662
当前系统名称 . . . . . . . . . . . .. . . :S1028662
挂起系统名称. . . . . . . . . . . . . . . .:
本地网络标识. . . . . . . . . . . . . . :APPN
本地控制点名称. . . . . . . . . . . . . . . :S1028662
缺省本地地址. . . . . . .. . . . . . . . . :S1028662
缺省模式. . . . . . . . . . . . . . . :BLANK
APPN 节点类型. . . . . . . . . . . . . :*ENDNODE
最大中间会话数. . . . . . . . . . . . .. . . . . . :200
路由附加电阻 . . . . . . . . . . . . . . . . :128
服务器网络标识/控制点名称. . . . . . . . . . .:

更多信息...
按 Enter 继续。

F3=退出 F12=取消

启动 EHLLAPI 映射公用程序

按下列步骤来使用 EHLLAPI 映射公用程序实例:

  1. 启动 EHLLAPI 映射公用程序。
  2. 启动一个通信管理器终端仿真会话(此会话命名为会话“A”)。
  3. 注册并发出显示 AS/400 网络属性的命令。

用 EHLLAPI 映射公用程序创建映射

完成上节中的步骤后,就可捕捉屏幕。

选择 Example.scr 作为屏幕文件名(尽管真实接口可能使用更具说明性的名称,如 dnetattr.scr)。以此屏幕文件名为基础,创建名为 example.map 的映射。

要使此例变得简单有效:

下表详细说明每个映射条目所用的信息:

映射条目 说明
currentSystemName 长度为 8,系统格式为 DEFAULT_FORMAT,TSD 脚本类型为 STRING。
pendingSystemName 长度为 8,系统格式为 DEFAULT_FORMAT,TSD 脚本类型为 STRING。
localNetworkID 长度为 8,系统格式为 LEFT_JUSTIFY,TSD 脚本类型为 STRING。
localCPName 长度为 8,系统格式为 DEFAULT_FORMAT,TSD 脚本类型为 STRING。
dfltLocalLocation 长度为 8,系统格式为 DEFAULT_FORMAT,TSD 脚本类型为 STRING。
dfltMode 长度为 8,系统格式为 LEFT_JUSTIFY。
APPNNodeType 长度为 8,系统格式为 DEFAULT_FORMAT,TSD 脚本类型为 INTEGER。
maxNbrIntSess 长度为 4,系统格式为 LEFT_JUSTIFY,TSD 脚本类型为 INTEGER。
routeAddRes 长度为 3,系统格式为 LEFT_JUSTIFY,TSD 脚本类型为 INTEGER。

这些系统格式(DEFAULT_FORMAT 除外)由上载操作使用。对于下载操作,从值中去掉空格。未为此映射设置标题属性;而是使用了缺省设置。

创建所有条目后,将此映射保存为 EXAMPLE.MAP。EHLLAPI 映射公用程序产生一个与下列实例相似的文件。此实例执行简单的下载操作。但是,它可说明使用 EHLLAPI 映射公用程序创建映射的基本步骤。

*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

创建网络标识的映射条目

在本节中,将创建服务器网络标识的映射条目。有五个字段可包含服务器网络标识。

通过将指针从第一个字段的第一个字符拖动到最后一个字段的最后一个字符,创建名为 srvrNetworkID 的条目,且 EHLLAPI 映射公用程序认为此条目是多行字段。创建名为 ParseSrvrNames 的用户格式函数。

此格式函数与下列实例相似:

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

声明 srvrNetworkID 作为记录中的字符串列表:

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;

运行下载函数时,用正确的值更新此列表。可能会发现此方法比重复调用 EMUFillBuffer、或创建 TSD 脚本记录中的哑元字段以下载映射中的所有字段,然后以一次一个值的方式将值插入到此列表的方法更灵活。


Tivoli 服务台 6.0 开发工具包旧 API 指南

返回目录

版权所有