联想金融事业部：SOP报文API使用说明.doc

联想电脑金融应用服务事业部SOP报文API使用说明1. 概述SOP报文API是为了方便在外挂系统中使用SOP报文而提供的一套库函数，以节省第三方的开发时间。2. SOP报文结构请参照SOP通讯规则。3. 总体结构4. 目录结构syscfg 系统配置文件mapfile 交易格式文件log 日志api SOP报文API及相关文档5. 环境变量SOPHOME SOP目录6. API函数说明/* 模块名 : 初始化转换环境 参 数 : iUseEucpFlag - 转换类型，固定为USE_COP 返回值 : 0 - 成功 0 - 失败*/int InitConEnv(int iUseEucpFlag);/* 模块名 : 释放转换环境 参 数 : 无 返回值 : 无*/void DestoryConEnv(void);/* 模块名 : SOP报文拆包函数 参 数 : pRecordBuf - 报文 iRecordBufLen - 报文长度 pczPktFmt - 报文格式 返回值 : 0 - 成功 0 - 失败 说 明 : pczPktFmt - 报文格式 格式文件名格式类型 格式类型: S - 上传报文，R - 下传报文 比如: O61400S，O61401R*/int ConvertPktToPool(char * pRecordBuf, int iRecordBufLen, char *pczPktFmt);/* 模块名 : SOP报文打包函数 参 数 : pRecordBuf - 报文缓冲区 iRecordBufLen - 报文缓冲区长度 pczPktFmt - 报文格式 返回值 : 0 - 成功 =0 - 数据项值的长度 -1 - 失败 -2 - 数据项未找到*/int PGetStr(char *c_pczName,char *c_pczBuf,int c_iBufLen);/* 模块名 : 在POOL池中放入一内存数据 参 数 : c_pczName - 数据项的名字 c_pVal - 数据项的值 c_iValLen - 数据项值的长度 返回值 : 0 - 成功 -1 - 失败*/int PPutMem(char *c_pczName,void *c_pVal,int c_iValLen);/* 模块名 : 从POOL池中取出一内存数据 参 数 : c_pczName - 数据项的名字 c_pBuf - 数据缓冲区 c_iBufLen - 数据缓冲区长度 返回值 : =0 - 数据项值的长度 -1 - 失败 -2 - 数据项未找到*/int PGetMem(char *c_pczName,void *c_pBuf,int c_iBufLen);/* 模块名 : 打印POOL池中的所有数据项 参 数 : 无 返回值 : 无*/void POOL_PrintData();/* 模块名 : 在日志文件中打印POOL池中的所有数据项 参 数 : 无 返回值 : 无*/void POOL_TraceData();7. 常见错误1、 初始化转换环境失败原因：未设置环境变量SOPHOME2、 生成SOP的上/下传报文失败原因：首先比较两端的mapfile是否一致，其次检查通讯的返回报文是否正确，其他原因请查看log目录下的日志文件8. 有关打印对象的支持由于打印的行列坐标生成在SOP的报文中，而mafile文件中并不包含打印坐标的定义，为了增加对打印坐标的支持，在原mafile文件9列的基础上，在后面增加3列（仅仅针对打印对象），分别为行坐标、列坐标、打印模式，而报文API也做了相应的改动。SOP对象格式中的打印属性（行坐标、列坐标、打印模式）在打印对象中才用到。至于打印控制命令，若没有特殊需要，不需使用。以下关于mapfile文件格式的介绍没有包含此新增3列。9. 有关表格的操作表格的格式如下：本报文API并不对表格对象的具体内容进行打/拆包，而是把表格内容的整段报文打入/读出POOL池。以上面的表格为例，拆包时，拆包函数把表格名开始的报文内容按照名字”F01”打入POOL池，由应用自行对表格内容进行处理；打包时，应用先自行组织表格内容，然后按照名字”F01”把表格内容打入POOL池，再调用打包函数。本报文API提供两个对表格进行操作的通用函数，大家可以根据需要自行选择使用。 int SOP_PackForm(char *c_pczFormName,char c_cPrintFlag, char *c_pcBuf,int c_iBufLen,int *c_piRetLen); c_pczFormName - 表格名 c_cPrintFlag - 是否打印表格，0-非打印表格，1-打印表格，对于打印表格，格式文件中的字段定义后加多3列，分别为行坐标、列坐标、打印模式 c_pcBuf - 输出缓冲区 c_iBufLen - 输出缓冲区长度 c_piRetLen - 实际表格报文的长度 int SOP_UnpackForm(char c_cPrintFlag,char *c_pcPkt,int c_iPktLen); c_cPrintFlag - 是否打印表格 c_pcPkt - 表格报文 c_iPktLen - 表格报文的长度 使用方法：/* 准备表格数据 */iRows=3;for (i=0;iiRows;i+)sprintf(aczSuff,_%d,i);POOL_SetPutSuff(aczSuff);/* 设置POOL池数据名后缀 */PPutStr(PAAAAA,);PPutStr(PABBBB,);PPutStr(PACCCC,);POOL_SetPutSuff();/* 清除POOL池数据名后缀，非常重要，出错退出时请不要忘记 */* 设置表格的行数 */PPutMem(F61401_Rows,&iRows,sizeof(int);/* 调用表格打包函数 */iRetCode=SOP_PackForm(F61401,0,acBuf,sizeof(acBuf),&iLen);if ( iRetCode0 )return -1;/* 把表格报文放入POOL池 */PPutMem(F61401,acBuf,iLen);/* 从POOL池中取出表格报文 */iLen=PGetMem(F61401,acPkt,sizeof(acPkt);/* 调用表格拆包函数 */iRetCode=SOP_UnpackForm(0,acPkt,iLen);if ( iRetCode0 )return -1;/* 取出表格的行数 */PGetMem(F61401_Rows,&iRows,sizeof(int);/* 使用表格数据 */for (i=0;iiRows;i+)sprintf(aczSuff,_%d,i);POOL_SetGetSuff(aczSuff);/* 设置POOL池数据名后缀 */PGetStr(PAAAAA,);PGetStr(PABBBB,);PGetStr(PACCCC,);POOL_SetGetSuff();/* 清除POOL池数据名后缀，非常重要，出错退出时请不要忘记 */10. 有关应答报文的组织memset(aczBuf,0,sizeof(aczBuf);/* 系统信息头 system_head.cfg */* 报文长度由系统自动加入 */PPutMem(sysSADDR,aczBuf,4);/* 源地址 */PPutMem(sysDADDR,aczBuf,4);/* 目的地址 */PPutMem(sysRSRVD,aczBuf,1);/* 系统保留位 */aczTemp0=0x01;PPutMem(sysEFLAG,aczTemp,1);/* 信息结束标志 */PPutMem(sysSEQNUM,aczBuf,2);/* 报文序号 */PPutMem(sysMACFLAG,aczBuf,1);/* 校验标志 */PPutMem(sysMACVALUE,aczBuf,8);/* 校验值 */* 公共交易头 cmtran_rcv_head.cfg */PPutStr(PDTRCD,6140);/* 交易代码 */PPutStr(PDLDTC,);/* 联动交易码 */PPutStr(PDTRDT,20021010);/* 交易日期 */iNow=htonl(91020);/* 09:10:20 */PPutMem(PDTRTM,(char *)&iNow,4);/* 交易时间 */PPutStr(PDTLSQ,888888880001);/* 柜员流水号 */PGetMem(PDTRSQ,aczTemp,2);PPutMem(PDERTR,aczTemp,2);/* 出错交易序号 */PPutStr(TPU_RetCode,AAAAAAA);/*返回码，不超过7位，AAAAAAA代表成功应答，其它为失败应答*/* 组织下传报文的交易数据 */* 生成SOP的下传报文 */iSendLen=ConvertPoolToPkt(aczSendMsg,sizeof(aczSendMsg),O61401R);if ( iSendLen0 )printf(生成SOP的下传报文失败(%d)n,iSendLen);DestoryConEnv();return -1;11. 有关失败应答报文的组织首先，在公共交易头中的TPU_RetCode变量不是AAAAAAA，/* 组织失败应答报文的交易数据 */PPutStr(“TPU_Ctx1”,”ERR000”);/* 失败对象名，固定为”ERR000” */PPutStr(“TPU_Ctx2”,”-1”);/* 错误码，固定为”-1” */PPutStr(“TPU_RetMsg”,”XXXXX”);/* 返回信息，不超过82位 */成功应答报文和失败应答报文的打/拆包使用同一函数和参数。12. Mapfile的文件格式通讯打包数据的配置，包括对象配置文件和GRID配置文件，其格式为：第一行指明该对象的输出方向，WINDOW代表窗口，PRINTER代表打印机，从第二行起格式如下：（可以有任意行）FLD|GRD:name len type scale align fillchar turnmode string encrypt（对于GRID，只能有FIELD，配置文件名就是GRID的名字），具体字段的含义由应用层定（都是由后台接口文件自动生成）。其意义分别是：FLD|GRD字段或表格标识，当为GRD时，后面只有name项namefield字段名称或表格Grid名称len字段长度，为实际的存储长度,如整型为4type字段类型，n-short，N-integer，L-long，D-decimal，S-char，Q-date ，T-time，H-hex，B-CHNscale小数点后位数align对齐方式，0-左对齐 1-右对齐 2-中对齐 3-无对齐fillchar填充字符turnmode转换模式，1-将传回的数据转为汉字金额2-转换为列表中的内容3-将数据转换为日期大写4-为空不打印5-不管为不为空都不打印string如果要转换成列表内容,则指明列表名,否则为空(填NULL)encrypt加密标志，1-加密，0-不加密例如：O93132WINDOWFLD:GUIYDH 8 S 0 0 0 0 NULL 0FLD:GUIYXM 22 S 0 0 0 0 NULL 0FLD:QISHRQ 8 Q 0 0 0 0 NULL 0FLD:ZZHIRQ 8 Q 0 0 0 0 NULL 0GRD:F931301F931301PRINTERFLD:HUOBDH 2 S 0 0 0 0 NULL 0FLD:JIEDBZ 1 S 0 0 0 0 NULL 0FLD:XJDFSE 13 D 2 0 0 0 NULL 0FLD:XJDFBS 7 L 0 0 0 0 NULL 0FLD:ZZDFSE 13 D 2 0 0 0 NULL 0FLD:ZZDFBS 7 L 0 0 0 0 NULL 013. 表格报文（SOP