Tivoli 服务台 6.0 开发工具包接口设计器指南
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 |
|
INTEGER |
|
BOOLEAN |
|
REAL |
|
TIME |
|
DATE |
|
在某些情况下,可能希望在 TSD 脚本中编写您自己的格式函数。用户定义的格式函数接受输入数据,将数据转换为新格式,然后返回 Boolean 值以指示所做的操作是否成功。用户定义的格式函数的原型为:
FUNCTION {funcname}(VAL {source}:{sourcetype}, REF {target}:{targettype}):BOOLEAN
下面是对用户定义的格式函数的说明:
用户定义的格式函数 | 说明 |
sourcetype |
|
targettype |
|
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
尽管映射文件很简单,但是手动创建整个接口应用程序的映射文件可能很费时间。
通过对行和列进行计数以正确确定主机屏幕位置很容易造成人为的错误,特别是当开发人员面对许多屏幕且每个屏幕包含许多字段时,更是如此。
大多数接口开发人员宁愿花时间解决接口的数理逻辑问题。
如果用户只有可查看的文本文件,则在以后的某个日期对映射文件进行修改(或由别的人来修改)是很困难的。
为了解决上述问题,Tivoli Systems 创建了 EHLLAPI 映射公用程序。
EHLLAPI 映射公用程序提供创建映射文件的直观方法,这些文件由 TSD 脚本 EMUMapUpload 和 EMUMapDownload 所使用。
EHLLAPI 映射公用程序使您能捕捉主机屏幕并将其保存为文本文件(SCR 文件)。当选择希望为其创建字段条目的字段时,根据捕捉到的屏幕创建映射文件。可通过单击并拖动字段来选择字段条目。
此外,EHLLAPI 映射公用程序对接口维护很有用,这是因为此工具可装入以前捕捉到的 SCR 文件并使任意映射文件应用于屏幕。有了 EHLLAPI 映射公用程序,就可以以直观形象的方式创建、查看、编辑和删除字段条目。
EHLLAPI 映射公用程序都是在 TSD 脚本中编写的。如果希望修改 TSD 脚本代码,则 Tivoli Systems 建议在开始修改前对原始代码(maputil.kb、mapentry.df)做备份。
为了使用 EHLLAPI 映射公用程序,必须在机器上安装 TSD 开发工具包。而只有安装了 TSD 开发工具包的 EHLLAPI 扩展,才能使用“捕捉”选项。
要启动此工具:
查看从主机捕捉到的屏幕时,会看到一些在终端窗口看不到的字符。这些字符是隐藏的主机字符,作为字段定界符使用。因为这些字符有助于确定字段的开头和结尾,因此 EHLLAPI 映射公用程序不剔除这些字符。
您自己应该熟悉的第一个操作是捕捉主机屏幕。首先为任意主机屏幕设置上载/下载操作很有必要。
捕捉屏幕时,进行了下列操作:
Tivoli Systems 约定捕捉的屏幕文件的扩展名为 .SCR,但是您在命名此文件时可以选择希望使用的任意扩展名。
要捕捉主机屏幕:
注:捕捉屏幕后,“捕捉主机屏幕”菜单命令变为不活动状态。
如果希望捕捉另一个主机屏幕:
EHLLAPI 映射公用程序窗口可改变大小。如果有部分主机屏幕不可见,则可改变窗口的大小直到整个屏幕都是可见的。如果窗口太大,则不能为主机屏幕以外的区域创建映射条目。
注:只能使用终端仿真会话来捕捉屏幕。所有其他 EHLLAPI 映射公用程序操作只能使用 TSD 开发工具包。这样,即使使用没有安装通信管理器的机器,也可以一次捕捉许多屏幕,以后再创建映射。
如果希望装入以前捕捉到的屏幕文件:
装入屏幕文件后,“装入屏幕文件”变为不活动的。如果希望装入另一个屏幕:
装入屏幕文件后,就可为此屏幕创建映射文件。
要选择为其创建映射条目的字段:
如果指针拖动太快,则高亮区域可能不包括此字段的第一个字符。如果出现这样的情况,则重复以上步骤。
要为高亮区域创建条目:
要编辑映射条目:
注:双击对象与单击它再选择“编辑条目”等价。
要删除映射条目:
要设置此映射文件的标题信息:
要保存未命名的映射文件(或如果想用不同的名称来保存此文件):
如果要保存已命名的映射:
将映射文件应用到屏幕,可使用户读取指定的映射文件并高亮显示在此映射文件中找到的映射条目。当用户需要添加或更改映射文件时,这很有用。
要将映射文件应用到屏幕:
应用映射后,可编辑、删除映射中的条目以及向映射添加条目。
显示屏幕时,或如果将映射应用到屏幕,可能不能使用一些“文件”菜单命令。如果需要捕捉新屏幕或装入不同的屏幕文件,则需要使当前显示器复位。
要使当前显示器复位:
要更改公用程序窗口所用的字体:
注:当关闭 EHLLAPI 映射公用程序时,不保存字体设置。
可使用下列方法之一退出 EHLLAPI 映射公用程序的执行:
如果选择退出但未保存最近的更改,则出现一条消息,询问是否要保存此文件。
如果选择“是”且文件未命名,则出现一个文件对话框,使您能命名此文件。
此例显示列出网络属性信息的 AS/400 屏幕。在此例中,您:
可在 OS2ASE 目录中找到这些实例文件(名为 example.scr、example.kb 和 example.map)。
主机屏幕与下列实例相似:
显示网络属性系统:
系统:
S1028662
当前系统名称 . . . . . . . . . . . .. . . :S1028662
挂起系统名称. . . . . . . . . . . . . . . .:
本地网络标识. . . . . . . . . . . . . . :APPN
本地控制点名称. . . . . . . . . . . . . . . :S1028662
缺省本地地址. . . . . . .. . . . . . . . . :S1028662
缺省模式. . . . . . . . . . . . . . . :BLANK
APPN 节点类型. . . . . . . . . . . . . :*ENDNODE
最大中间会话数. . . . . . . . . . . . .. . . . . . :200
路由附加电阻 . . . . . . . . . . . . . . . . :128
服务器网络标识/控制点名称. . . . . . . . . . .:
更多信息...
按 Enter 继续。
F3=退出 F12=取消
按下列步骤来使用 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 指南