HP NonStop Data Transformation Engine Platform API Reference Guide Abstract This guide provides information about the HP NonStop™ Data Transformation Engine (NonStop DTE) Platform API. Product Version NonStop Data Transformation Engine 6.7.
Document History Part Number Product Version Published 427643-001 NonStop Data Transformation Engine 1.0 December 2000 522446-001 NonStop Data Transformation Engine 5.0.3 November 2001 522446-002 NonStop Data Transformation Engine 6.7.
&RQWHQWV $ERXW 7KLV 'RFXPHQW 5HODWHG 5HIHUHQFHV &KDSWHU 3ODWIRUP $3, 2YHUYLHZ ,QVWDOOHG )LOHV ([DPSOH )LOHV
Contents &KDSWHU 3ODWIRUP $3, )XQFWLRQV )XQFWLRQ 'HVFULSWLRQV 0HUF,QLW$3, )XQFWLRQ 0HUF([LW$3, )XQFWLRQ 5XQ0DS )XQFWLRQ ,QLWLDOL]H5XQ0DS,QVWDQFH )XQFWLRQ
$ERXW 7KLV 'RFXPHQW 7KLV GRFXPHQW FRQWDLQV LQIRUPDWLRQ DERXW WKH 3ODWIRUP $SSOLFDWLRQ 3URJUDPPLQJ ,QWHUIDFH $3, 7KLV GRFXPHQW DVVXPHV WKDW \RX SRVVHVV D ZRUNLQJ NQRZOHGJH RI \RXU RSHUDWLQJ HQYLURQPHQW DUH IDPLOLDU ZLWK WKH & SURJUDPPLQJ ODQJXDJH DQG DUH IDPLOLDU ZLWK WHUPLQRORJ\ VXFK DV PHPRU\ PXOWL WKUHDGHG HQYLURQPHQW YDULDEOHV DQG ILOH ORFNLQJ ,W DOVR DVVXPHV WKDW \RX KDYH XVHG WKH 'HVLJQ 6WXGLR DQG XQGHUVWDQG WKH EDVLF WHUPLQRORJ\ VXFK DV PDS WUDFH ILOHV DXGLW ILOHV ZRUN ILOHV DGDSWH
&KDSWHU 3ODWIRUP $3, 7KLV FKDSWHU LQWURGXFHV WKH 3ODWIRUP $3, DQG GHVFULEHV LQ D JHQHUDO VHQVH RI KRZ LW LV XVHG ,W DOVR GHVFULEHV ZKLFK ILOHV DUH LQFOXGHG ZLWK WKH 3ODWIRUP $3, 2YHUYLHZ 7KH 3ODWIRUP $3, SURYLGHV WLJKW LQWHJUDWLRQ RI WKH &RPPDQG RU (YHQW 6HUYHU LQWR XVHU DSSOLFDWLRQV LQFOXGLQJ WKRVH FUHDWHG XVLQJ GHYHORSPHQW WRROV VXFK DV 9LVXDO %DVLF 7KH 3ODWIRUP $3, LV EDVHG RQ WKH FRPPDQG RSWLRQV DYDLODEOH IRU WKH SDUWLFXODU GHYHORSPHQW SODWIRUP 7KHVH RSWLRQV H[SODLQHG LQ WKH ([HFXWLRQ
Chapter 1 - Platform API Example Files )LOH 'HVFULSWLRQ WHVWDSLG F 6DPSOH µ&¶ SURJUDP LOOXVWUDWLQJ KRZ WR G\QDPLFDOO\ ORDG WKH 3ODWIRUP $3, DQG KRZ WR VHW WKH H[LW URXWLQH DQG XQORDG LQ WKH 3ODWIRUP $3, LQ WKH H[LW URXWLQH 81,; RQO\ 1RWH 7KLV VDPSOH µ&¶ SURJUDP LV IRU WKH 6XQ RSHUDWLQJ V\VWHP 7KH DFWXDO LPSOHPHQWDWLRQ RQ RWKHU V\VWHPV PD\ EH VOLJKWO\ GLIIHUHQW EXW WKH FRQFHSW LV WKH VDPH ([DPSOH )LOHV 7R DFFHVV DQ H[DPSOH IRU WKH 3ODWIRUP $3, FOLFN 6WDUW ! 3URJUDPV ! 0HUFDWRU ; [[
&KDSWHU 8VLQJ WKH 3ODWIRUP $3, 7KLV FKDSWHU GHVFULEHV KRZ WR XVH WKH 3ODWIRUP $3, IXQFWLRQV DQG VWUXFWXUHV WR LQWHJUDWH PDSSLQJ SURFHVVHV ZLWKLQ \RXU DSSOLFDWLRQ 1RWH 7KH 3ODWIRUP $3, LV D & OLEUDU\ 3ODWIRUP $3, 8VDJH *XLGHOLQHV 7KH IROORZLQJ VHFWLRQV GHVFULEH WKH JXLGHOLQHV IRU XVLQJ WKH 3ODWIRUP $3, 1RWH 7KH IROORZLQJ SURFHGXUH DVVXPHV WKDW \RX KDYH D SUHYLRXVO\ FUHDWHG PDS RU V\VWHP To use the Platform API 1 2 )URP ZLWKLQ \RXU DSSOLFDWLRQ LI \RXU PDS XVHV DQ DGDSWHU GDWDEDVH PH
Chapter 2 - Using the Platform API Platform API Usage Guidelines ,Q WKH VLPSOHVW VLWXDWLRQ WR UXQ VGT PPF \RXU SURJUDP PD\ ORRN OLNH WKH IROORZLQJ #include “windows.h” #include #include “runmerc.h” int main(void) { EXITPARAM ExitParam; MercInitAPI(); memset(&ExitParam,0,sizeof(EXITPARAM)); ExitParam.lpDataToApp = (unsigned char *)“sdq.mmc -ae -ts -p32:8\0”; ExitParam.dwSize = sizeof(EXITPARAM); ExitParam.lpv = NULL; RunMap(&ExitParam); printf(“Map returned %d: %s\n”, ExitParam.
Chapter 2 - Using the Platform API Whose Memory Is It Anyway? 7KH 5XQ &RPPDQG DQG &RPPDQG 2SWLRQV 7R H[HFXWH D PDS IURP ZLWKLQ WKH 3ODWIRUP $3, VSHFLI\ D VWDQGDUG UXQ FRPPDQG DV DQ DUJXPHQW WR WKH RunMap IXQFWLRQ $ UXQ FRPPDQG LV GHILQHG DV mapset[ mapset](s)]|[@command-file-name](s) ZKHUH mapset LV GHILQHG DV map-name[ command-option-list] DQG command-option-list LV GHILQHG DV command-option[ command-option(s)] 7KH FRQWHQW RI D FRPPDQG ILOH LV GHILQHG DV mapset[ mapset] (s) ZKHUH map-nam
Chapter 2 - Using the Platform API Data To and From the Platform API 6HH $SSHQGL[ $ 5HWXUQ &RGHV DQG (UURU 0HVVDJHV IRU D OLVW RI WKH HUURU FRGHV WKDW UHVXOW ZKHQ DQ LQYDOLG FRPPDQG OLQH LV VSHFLILHG LQ lpDataToApp IRU WKH 3ODWIRUP $3, 'DWD 7R DQG )URP WKH 3ODWIRUP $3, 8VH ,QSXW 6RXUFH 2YHUULGH ± (FKR H[HFXWLRQ FRPPDQG -IE IRU D VRXUFH RU WDUJHW WR SDVV GDWD DV LQSXW IURP \RXU DSSOLFDWLRQ WR D PDS RU WR UHFHLYH GDWD DV RXWSXW RI D PDS ZLWKRXW XVLQJ ILOHV RU DSSOLFDWLRQV 3DVVLQJ ,QSXW 'DWD
Chapter 2 - Using the Platform API Data To and From the Platform API 5HWXUQLQJ 'DWD IURP D 0DS :KHQ \RX GR QRW RYHUULGH DQ\ RI WKH PDS¶V WDUJHWV ZLWK WKH 2XWSXW 7DUJHW 2YHUULGH ± (FKR H[HFXWLRQ FRPPDQG -OE lpDataFromApp FRQWDLQV WKH VWULQJ UHSUHVHQWDWLRQ RI nReturn.
Chapter 2 - Using the Platform API Using Maps in Memory /* lpDataFromApp now contains the output from card 1 that was mapped */ /* dwFromLen is the size of the output */ . . .
Chapter 2 - Using the Platform API Using Maps in Memory 7KH IROORZLQJ VDPSOH FRGH XVHV WKH RunMap IXQFWLRQ WR FDOO D PDS VGT PPF WKDW KDV EHHQ LQLWLDOL]HG LQWR PHPRU\ 1RWH ,Q WKH FRGH EHORZ lpv LV DQ LPVOID W\SH VHW ZLWKLQ WKH XVHU¶V SURJUDP /* declare a new local variable: */ LPVOID lpv; /* to initialize, do these two steps */ /* this gets a pointer to a map instance: */ lpv = InitializeRunMapInstance(“sdq.
Chapter 2 - Using the Platform API MERC_DO_NOT_CHDIR for NT 0(5&B'2B127B&+',5 IRU 17 'XULQJ UXQWLPH E\ GHIDXOW WKH $3, FKDQJHV WR WKH GLUHFWRU\ ZKHUH WKH FRPSLOHG PDS LV ORFDWHG 7R GLVDEOH WKLV IHDWXUH VHW WKH MERC_DO_NOT_CHDIR HQYLURQPHQW YDULDEOH WR 758( )RU H[DPSOH MERC_DO_NOT_CHDIR=TRUE 1RWH 8VH FDXWLRQ ZKHQ HQDEOLQJ WKH MERC_DO_NOT_CHDIR HQYLURQPHQW YDULDEOH $Q\ UHIHUHQFHV WR UHODWLYH SDWKV LQ WKH PDSSLQJ PD\ QRW UHPDLQ UHODWLYH WR WKH FRPSLOHG PDS DV UHTXLUHG )RU GHWDLOHG LQIRUPDWLR
&KDSWHU 8VLQJ WKH $3, RQ D 81,; 3ODWIRUP 7KLV VHFWLRQ LQWURGXFHV HQYLURQPHQW YDULDEOHV WKDW FDQ EH VHW IRU WKH 3ODWIRUP $3, WR GHILQH WKH ORFDWLRQ IRU WHPSRUDU\ ILOHV WR SURGXFH HQYLURQPHQWDO GHEXJJLQJ LQIRUPDWLRQ DQG WR FRQWURO ILOH ORFNLQJ IDFLOLWLHV 7KHVH IHDWXUHV DUH DYDLODEOH IRU DOO 81,; SODWIRUPV RQ ZKLFK WKH 3ODWIRUP $3, LV DYDLODEOH 1RWH 7KH 1RQ6WRS VHUYHU SODWIRUP GRHV QRW XVH G\QDPLF OLQN OLEUDULHV $Q\ VHFWLRQV LQ WKLV PDQXDO WKDW GHVFULEH VKDUHG OLEUDULHV DQG VKDUHG OLEUDU\ SDW
Chapter 3 - Using the API on a UNIX Platform Configuring the UNIX Environment &RQILJXULQJ WKH 81,; (QYLURQPHQW 7KH IROORZLQJ VHFWLRQV GHVFULEH WKH JXLGHOLQHV IRU FRQILJXULQJ WKH 3ODWIRUP $3, LQ D 81,; HQYLURQPHQW 1RWH 7KH 1RQ6WRS VHUYHU SODWIRUP GRHV QRW XVH G\QDPLF OLQN OLEUDULHV $Q\ VHFWLRQV LQ WKLV PDQXDO WKDW GHVFULEH VKDUHG OLEUDULHV DQG VKDUHG OLEUDU\ SDWK /,%3$7+ YDULDEOHV GR QRW DSSO\ WR WKLV SODWIRUP (QYLURQPHQW 9DULDEOH 6HWXS 3URJUDP %HIRUH H[HFXWLQJ D PDS H[HFXWH WKH VHWXS SURJU
Chapter 3 - Using the API on a UNIX Platform Configuring the UNIX Environment (QDEOLQJ (QYLURQPHQWDO 'HEXJ 7R HQDEOH WKLV HQYLURQPHQWDO GHEXJ RU WUDFH IDFLOLW\ VHW WKH MERC_DEBUG HQYLURQPHQW YDULDEOH WR TRUE )RU H[DPSOH MERC_DEBUG=TRUE export MERC_DEBUG 7KLV HQYLURQPHQWDO GHEXJ LQIRUPDWLRQ LV ZULWWHQ WR D ILOH QDPHG PHUFLQIR ORJ LQ WKH GLUHFWRU\ LGHQWLILHG E\ WKH MERC_TMP_DIR HQYLURQPHQW YDULDEOH ,I WKH MERC_TMP_DIR HQYLURQPHQW YDULDEOH LV QRW VHW mercinfo.
Chapter 3 - Using the API on a UNIX Platform Configuring the UNIX Environment )LOH /RFNLQJ 0(5&B),/(B/2&.
Chapter 3 - Using the API on a UNIX Platform Configuring the Map Execution Environment (QDEOLQJ 'R 1RW &KDQJH 'LUHFWRU\ 7R HQDEOH WKH GR QRW FKDQJH GLUHFWRU\ IDFLOLW\ VHW WKH MERC_DO_NOT_CHDIR HQYLURQPHQW YDULDEOH WR 758( )RU H[DPSOH MERC_DO_NOT_CHDIR=TRUE export MERC_DO_NOT_CHDIR 1RWH 7KH MERC_DO_NOT_CHDIR variable can only be used in cases of absolute path names.
Chapter 3 - Using the API on a UNIX Platform Using the Platform API with Database Adapters (QDEOLQJ )LOH /RFNLQJ )LOH ORFNLQJ LV HQDEOHG E\ GHIDXOW 6HWWLQJ WKH HQYLURQPHQWDO GHEXJ IDFLOLW\ LV RSWLRQDO WR WKH ILOH ORFNLQJ IDFLOLW\ 7R HQDEOH WKH HQYLURQPHQWDO GHEXJ IDFLOLW\ VHW WKH MERC_DEBUG HQYLURQPHQW YDULDEOH WR TRUE 7R HQDEOH WKH ILOH ORFNLQJ IDFLOLW\ VHW WKH MERC_FILE_LOCKING HQYLURQPHQW YDULDEOH WR TRUE )RU H[DPSOH MERC_FILE_LOCKING =TRUE export MERC_FILE_LOCKING 1RWH 7R XVH WKLV ILOH O
&KDSWHU 8VLQJ WKH $3, RQ 26 7KLV VHFWLRQ LQWURGXFHV WKH 3ODWIRUP $3, IRU 26 &XUUHQWO\ 0HUFDWRU VXSSRUWV WZR H[HFXWLRQ HQYLURQPHQWV RQ 26 EDWFK DQG &,&6 7KH FRPPDQG VHUYHU H[HFXWLRQ HQYLURQPHQW IRU &,&6 SURYLGHV D SURJUDPPLQJ LQWHUIDFH WKDW XWLOL]HV WKH &,&6 &RPPDQG /HYHO 3URJUDP &RQWURO $3,V 7KLV LQWHUIDFH HQDEOHV &2%2/ SURJUDPV WR FDOO WKH 0HUFDWRU VHUYHU RQ &,&6 LQ D IDVKLRQ VLPLODU WR WKH RunMap IXQFWLRQ GHVFULEHG LQ WKLV PDQXDO 7KH 0HUFDWRU &,&6 SURJUDPPLQJ LQWHUIDFH LV GRFX
Chapter 4 - Using the API on OS/390 Example Files for OS/390 &DOOLQJ WKH 3ODWIRUP $3, IURP D &2%2/ '// )URP D SURJUDPPLQJ SHUVSHFWLYH FDOOLQJ D '// IURP &2%2/ LV QRW PXFK GLIIHUHQW IURP D &2%2/ G\QDPLF &$// 7KH PDMRU GLIIHUHQFH LV WKDW WKH '// QDPH FDQ EH XS WR FKDUDFWHUV YHUVXV HLJKW IRU WKH WUDGLWLRQDO &2%2/ FDOO VWDWHPHQW 7KHUH DUH VRPH UHVWULFWLRQV VXFK DV WKH SURJUDP PXVW EH UHHQWUDQW 7KH IROORZLQJ &2%2/ FRPSLOHU RSWLRQV ZHUH XVHG WR FRPSLOH WKH 7(67&2% '// H[DPSOH SURJUDP CBL RE
Chapter 4 - Using the API on OS/390 Using the COB2CAPI module 7KH PDMRU GLIIHUHQFH EHWZHHQ WKH 26 YHUVLRQ RI WHVWDSL F YHUVXV WKH RWKHU SODWIRUPV LV WKDW WHVWDSL F FDOOV WKH 6'4 H[DPSOH PDS XVLQJ FRPPDQG OLQH RSWLRQV WKDW DUH XQLTXH WR 26 7R OHDUQ PRUH DERXW WKHVH FRPPDQG OLQH RSWLRQV UHIHU WR WKH &RPPDQG 6HUYHU 5HIHUHQFH *XLGH 3ODWIRUP $3, &2%2/ ([DPSOHV 7KHUH DUH WZR &2%2/ H[DPSOH SURJUDPV 7(67&2% DQG 767&2% & %RWK SURJUDPV GHPRQVWUDWH KRZ WR FDOO DOO RI WKH 3ODWIRUP $3, IXQFWLRQV IUR
Chapter 4 - Using the API on OS/390 Passing Function Parameters 3DVVLQJ )XQFWLRQ 3DUDPHWHUV 3DVVLQJ IXQFWLRQ SDUDPHWHUV WR WKH 3ODWIRUP $3, LV WKH VDPH ZKHWKHU LW LV FDOOHG DV D '// RU WKURXJK WKH &2% &$3, LQWHUIDFH ZLWK RQH H[FHSWLRQ 7KH CALLRMAP IXQFWLRQ KDV EHHQ HQKDQFHG WR WDNH DV LWV SDUDPHWHUV WKH PDS ILOH QDPH ExitParam VWUXFWXUH DGGUHVV DQG WKH DGGUHVV RI WKH DataFromApp 7KH RunMap IXQFWLRQ WDNHV RQO\ RQH SDUDPHWHU WKH ExitParam VWUXFWXUH DGGUHVV :KHQ XVLQJ WKH RunMap IXQFWLRQ WKH SR
Chapter 4 - Using the API on OS/390 PLATAPID DLL Import Definition 5HIHU WR &KDSWHU 3ODWIRUP $3, 6WUXFWXUH 'HILQLWLRQV IRU GHVFULSWLRQV RI WKH FRQWHQWV RI WKHVH FRS\ERRNV 1RWH 7KH YDULDEOH QDPHV FRQWDLQHG LQ WKH FRS\ERRNV DUH WKH VDPH DV WKH FRPSRQHQW QDPHV GRFXPHQWHG LQ &KDSWHU 3ODWIRUP $3, 6WUXFWXUH 'HILQLWLRQV H[FHSW WKH &2%2/ QDPHV DUH DOO LQ XSSHUFDVH ,Q DGGLWLRQ XQOLNH & D &2%2/ SURJUDP FDQQRW FRQWDLQ YDULDEOHV ZLWK WKH VDPH QDPH 7KHUHIRUH DQ\ YDULDEOH QDPH FRQWDLQLQJ D L
&KDSWHU 3ODWIRUP $3, )XQFWLRQV 7KLV FKDSWHU LQWURGXFHV WKH IXQFWLRQV WKDW PDNH XS WKH 3ODWIRUP $3, )XQFWLRQ 'HVFULSWLRQV 7KH IROORZLQJ WDEOH OLVWV WKH IXQFWLRQV WKDW PDNH XS WKH 3ODWIRUP $3, DQG SURYLGHV D EULHI GHVFULSWLRQ RI HDFK IXQFWLRQ¶V SXUSRVH 7KH IROORZLQJ SDJHV SURYLGH GHWDLOHG XVDJH LQIRUPDWLRQ IRU WKHVH IXQFWLRQV )XQFWLRQ 'HVFULSWLRQ $GDSWHU &RQQHFWLRQ DQG &OHDQXS MercInitAPI() (VWDEOLVKHV FRQQHFWLRQV IRU 0HUFDWRU DGDSWHUV GDWDEDVH PHVVDJLQJ XWLOLW\ DQG VR RQ Merc
Chapter 5 - Platform API Functions Function Descriptions 0HUF,QLW$3, )XQFWLRQ Syntax C int MercInitAPI(); OS/390 COBOL CALL ’MercInitAPI’ RETURNING RETCODE. COBOL – using COB2CAPI CALL ’CALLMERI’ RETURNING RETCODE.
Chapter 5 - Platform API Functions Function Descriptions 0HUF([LW$3, )XQFWLRQ Syntax C void MercExitAPI(); OS/390 COBOL CALL ’MercExitAPI’. OS/390 COBOL – using COB2CAPI CALL ’CALLMERE’.
Chapter 5 - Platform API Functions Function Descriptions 5XQ0DS )XQFWLRQ Syntax C void RunMap (LPEXITPARAM lpExitParam); OS/390 COBOL CALL ’RunMap’ USING BY REFERENCE EXITPARAM. OS/390 COBOL – using COB2CAPI CALL ’CALLRMAP’ USING BY REFERENCE EXITPARAM, MapFile, DataFromApp.
Chapter 5 - Platform API Functions Function Descriptions Returns 7KHUH LV QR UHWXUQ YDOXH +RZHYHU WKH nReturn szErrMsg DQG lpDataFromApp PHPEHUV RI WKH EXITPARAM VWUXFWXUH FRQWDLQ WKH PDS UHWXUQ FRGH PDS UHWXUQ PHVVDJH DQG DQ\ GDWD UHWXUQHG E\ WKH PDS DV D UHVXOW RI HFKRHG RXWSXWV UHVSHFWLYHO\ :KHQ FDOOLQJ RunMap WKH $3, ILOOV LQ WKH YDOXH RI nReturn EDVHG RQ WKH PDS¶V H[HFXWLRQ ,I PXOWLSOH PDSV DUH RQ WKH FRPPDQG OLQH nReturn LV EDVHG RQ WKH ODVW PDS RQ WKH FRPPDQG OLQH 6HH $SSHQGL[ $
Chapter 5 - Platform API Functions Function Descriptions Parameters )ROORZLQJ DUH SDUDPHWHUV IRU WKH InitializeRunMapInstance IXQFWLRQ Parameter Parameter Description lpszMapFile 7KH QDPH RI WKH FRPSLOHG PDS ILOH WR LQLWLDOL]H WR ORDG LQWR PHPRU\ Returns ,I VXFFHVVIXO InitializeRunMapInstance UHWXUQV D SRLQWHU WR EH XVHG IRU D VXEVHTXHQW FDOO WR RunMapInstance $ NULL UHWXUQ VLJQLILHV D IDLOXUH PRVW OLNHO\ PHDQLQJ WKH VSHFLILHG PDS GRHV QRW H[LVW See Also FreeRunMapInstance RunMapUsesI
Chapter 5 - Platform API Functions Function Descriptions Parameters )ROORZLQJ DUH SDUDPHWHUV IRU KH RunMapUsesInstance IXQFWLRQ Parameter Parameter Description lpep 7KH DGGUHVV RI WKH EXITPARAM VWUXFWXUH WR EH XVHG LQ D RunMap FDOO lpv 7KH UHWXUQ RI D FDOO WR WKH InitializeRunMapInstance IXQFWLRQ bSet ,QGLFDWRU RI ZKHWKHU WR VHW TRUE RU FOHDU FALSE WKH EXITPARAM VWUXFWXUH VSHFLILHG E\ lpep 1RWH ,I WKH RunMapUsesInstance IXQFWLRQ LV EHLQJ XVHG WR FOHDU WKH EXITPARAM VWUXFWXUH bSe
Chapter 5 - Platform API Functions Function Descriptions Description 8VH WKH FreeRunMapInstance IXQFWLRQ WR IUHH DOO WKH PHPRU\ DVVRFLDWHG ZLWK D PDS LQLWLDOL]HG XVLQJ WKH InitializeRunMapInstance IXQFWLRQ 7KH FreeRunMapInstance IXQFWLRQ LV XVHG ZLWK WKH RunMapUsesInstance IXQFWLRQ ZKHQ PDSV LQ PHPRU\ DUH QR ORQJHU UHTXLUHG Parameters )ROORZLQJ DUH SDUDPHWHUV IRU WKH FreeRunMapInstance IXQFWLRQ Parameter Parameter Description lpRunMapInstance 7KH SRLQWHU UHWXUQHG E\ WKH InitializeRunMapInsta
Chapter 5 - Platform API Functions Function Descriptions OS/390 COBOL – using COB2CAPI CALL ’CALLGCIO’ USING BY REFERENCE lpszMapFile, lpci, lpCardCount, lpExeOpts, RETURNING BOOL.
Chapter 5 - Platform API Functions Function Descriptions Returns ,I VXFFHVVIXO GetCardIOs UHWXUQV TRUE DQG lpci FRQWDLQV D SRLQWHU WR DQ DUUD\ RI CARDINFO VWUXFWXUHV ZLWK lpCardCount UHFHLYLQJ WKH FRXQW RI FDUGV 2WKHUZLVH GetCardIOs UHWXUQV FALSE 1RWH :KHQ GetCardIOs UHWXUQV FALSE LW PLJKW LQGLFDWH DQ LQFRPSDWLEOH YHUVLRQ RI WKH PDS ILOH ZLWK WKH UHOHDVH RI WKH 3ODWIRUP $3, 7KLV XVXDOO\ PHDQV WKH FRPSLOHG PDS ILOH LV LQYDOLG RU QHHGV WR EH UHFRPSLOHG ,I WKH UHWXUQ YDOXH RI GetCardIOs LV T
&KDSWHU 3ODWIRUP $3, 6WUXFWXUH 'HILQLWLRQV 7KLV VHFWLRQ GHILQHV WKH VWUXFWXUHV XVHG E\ WKH 3ODWIRUP $3, IXQFWLRQV WKHLU FRPSRQHQWV DQG XVDJH LQIRUPDWLRQ (;,73$5$0 6WUXFWXUH 7KH EXITPARAM VWUXFWXUH LV XVHG IRU WKH LQSXW DQG RXWSXW SDUDPHWHUV WR WKH RunMap IXQFWLRQ struct tagExitParamStruct { DWORD dwSize; DWORD dwToLen; DWORD dwFromLen; DWORD dwMapInstance; void FAR * lpv; LPSTR lpszCmdLine; BYTE HUGE * lpDataToApp; BYTE HUGE * lpDataFromApp; UINT uRetryCount; UINT uRetryInterval; BOOL bRollb
Chapter 6 - Platform API Structure Definitions EXITPARAM Structure (;,73$5$0 &RPSRQHQWV DQG 8VDJH 7KH EXITPARAM VWUXFWXUH KDV WKH IROORZLQJ FRPSRQHQWV WKDW DUH XVHG E\ WKH RunMap 1RWH 6RPH FRPSRQHQWV RI EXITPARAM DUH QRW XVHG ZLWK WKH 3ODWIRUP $3, EHFDXVH WKLV JHQHUDO VWUXFWXUH LV DOVR XVHG HOVHZKHUH WR SURYLGH D FRPPRQ LQWHUIDFH PHWKRG &RPSRQHQW 8VH dwSize 8VHG $V ,QSXW dwToLen dwFromLen 2XWSXW 7KH OHQJWK VL]H LQ E\WHV RI lpDataFromApp dwMapInstance * 0XVW EH VHW WR D XQ
Chapter 6 - Platform API Structure Definitions CARDINFO Structure &RPSRQHQW 8VHG $V 8VH lpAdaptParms 1RW XVHG lpContext 1RW XVHG lpWildcard 1RW XVHG dwWildcardSize 1RW XVHG lpszMapDirectory 1RW XVHG wCardNum 1RW XVHG wCleanupAction 1RW XVHG wScope 1RW XVHG uUnitSize 1RW XVHG bBurst 1RW XVHG lpfnMS 1RW XVHG lpMS 1RW XVHG dwRecords 1RW XVHG 1RWH 7KH dwMapInstance FRPSRQHQW PXVW EH VHW WR D XQLTXH QXPEHU IRU HDFK PDS WKDW
Chapter 6 - Platform API Structure Definitions BOOL BOOL BOOL BOOL bAppendBackup; bRollBackOnFailure; bRetrySwitch; bIgnoreAdapterWarnings; WORD WORD WORD WORD WORD wMapSuccessAction; wScope; wRetryAttempts; wRetryInterval; wFetchUnit; CARDINFO Structure WORD wUnused[9]; char szBackupFile[256]; }; &$5',1)2 &RPSRQHQWV 7KH CARDINFO VWUXFWXUH KDV WKH IROORZLQJ FRPSRQHQWV 3DUW 'HVFULSWLRQ wCard 7KH YDOXH RI WKH FDUG QXPEHU LQ WKH PDS ,I D PDS KDV WZR LQSXWV DQG WZR RXWSXWV wCard ZLOO KDYH WKH
Chapter 6 - Platform API Structure Definitions CARDINFO Structure 3DUW 'HVFULSWLRQ bIntegralMode ,QGLFDWHV ZKHWKHU WKH FDUG PRGH IRU DQ LQSXW FDUG LV ,QWHJUDO TRUE RU %XUVW FALSE &DUG 6HWWLQJ &DUG0RGH bSourceEvent ,QGLFDWHV ZKHWKHU WKH LQSXW FDUG LV EHLQJ XVHG DV D VRXUFH HYHQW TRUE bBackupSwitch ,QGLFDWHV ZKHWKHU WKH %DFNXS VZLWFK LV 21 TRUE RU 2)) FALSE IRU WKLV FDUG &DUG 6HWWLQJ bBackupAlways %DFNXS ! Switch ,QGLFDWHV ZKHWKHU WKH :KHQ VHWWLQJ IRU WKH %DFNXS RSWLR
Chapter 6 - Platform API Structure Definitions CARDINFO Structure 3DUW 'HVFULSWLRQ bIgnoreAdapterWarnings ,QGLFDWHV ZKHWKHU ZDUQLQJV UHWXUQHG E\ WKH DGDSWHU VKRXOG EH LJQRUHG TRUE RU QRW FALSE &DUG 6HWWLQJ wMapSuccessAction $GDSWHU:DUQLQJV ,QGLFDWHV DFWLRQ WR EH WDNHQ LI D PDS VXFFHVVIXOO\ H[HFXWHV 6HH ³Z0DS6XFFHVV$FWLRQ 6HWWLQJV´ RQ SDJH IRU SRVVLEOH YDOXHV &DUG 6HWWLQJ 2Q6XFFHVV ([HFXWLRQ &RPPDQG wScope 6FRSH RI WKH WUDQVDFWLRQ 6HH ³Z6FRSH 6HWWLQJV´ RQ SDJH IRU SRVV
Chapter 6 - Platform API Structure Definitions CARDINFO Structure Z,27\SH 6HWWLQJV 7KH wIOType DUJXPHQW KDV WKH IROORZLQJ VHWWLQJV &RQVWDQW 9DOXH 'HVFULSWLRQ MERC_DATAFILE 6RXUFH RU WDUJHW LV D GDWD ILOH MERC_STATICFILE 1RW YDOLG LQ WKLV XVDJH MERC_WORKFILE 1RW YDOLG LQ WKLV XVDJH MERC_TRACEFILE 1RW YDOLG LQ WKLV XVDJH MERC_BUFFER 1RW YDOLG LQ WKLV XVDJH MERC_DATABASE 6RXUFH RU WDUJHW LV D GDWDEDVH MERC_APPLICATION 6RXUFH RU WDUJHW LV DQ DSSOLFDWLRQ ± 8VHU
Chapter 6 - Platform API Structure Definitions &RQVWDQW 9DOXH CARDINFO Structure 'HVFULSWLRQ ADPT_SCOPE_BURST [ 6FRSH IRU WKH FDUG LV WKH EXUVW ADPT_SCOPE_CARD [ 6FRSH IRU WKH FDUG LV WKH FDUG Z0DS6XFFHVV$FWLRQ 6HWWLQJV 7KH wMapSuccessAction DUJXPHQW KDV WKH IROORZLQJ VHWWLQJV )RU DQ ,QSXW &DUG 7KH wMapSuccessAction DUJXPHQW KDV WKH IROORZLQJ VHWWLQJV IRU DQ LQSXW FDUG &RQVWDQW 9DOXH ADPT_KEEP_ALWAYS [ 'R QRW UHPRYH WKH LQSXW GDWD IURP LWV VRXUFH ADPT_KEEP_N
Chapter 6 - Platform API Structure Definitions EXEOPTS Structure $GGLWLRQDO &RQVWDQWV 6RPH DGGLWLRQDO FRQVWDQWV WKDW DUH DYDLODEOH &RQVWDQW 9DOXH 'HVFULSWLRQ MAX_TYPENAME /DUJHVW VL]H RI WKH FDUG QDPH LQ WKH &$5',1)2 VWUXFWXUH MAX_PATH /DUJHVW VL]H RI WKH ILOH QDPH LQ WKH &$5',1)2 VWUXFWXUH (;(2376 6WUXFWXUH 7KH EXEOPTS VWUXFWXUH LV XVHG WR SURYLGH LQIRUPDWLRQ DERXW WKH PDS VHWWLQJV FRPSLOHG LQWR WKH PDS struct tagExecutionOptions { DWORD dwTraceFlags; DWORD dwTraceInSta
Chapter 6 - Platform API Structure Definitions BOOL BOOL BOOL BOOL BOOL bCustomValidation; bCenturySwitch; bEveryMapWarning; bUniqueWorkFilePrefix; bUnused; WORD WORD WORD wDateResolution; wTraceICardNo; wTraceOCardNo; WORD WORD WORD WORD WORD wRetryCount; wRetryInterval; wPageSizeInK; wPageCount; wBurstErrorLimit; char char char szAuditDir[264]; szTraceDir[264]; szWorkDir[264]; EXEOPTS Structure }; typedef struct tagExecutionOptions EXEOPTS; typedef struct tagExecutionOptions; (;(2376 &RPSRQHQWV
Chapter 6 - Platform API Structure Definitions EXEOPTS Structure 3DUW 'HVFULSWLRQ bDataLog ,I bAuditOn LV 758( LQGLFDWHV WKDW WKH GDWD DXGLW ORJ LV WR EH FUHDWHG bAppendLog ,QGLFDWHV WKDW WKH DXGLW ORJ LQIRUPDWLRQ LV WR EH DSSHQGHG WR DQ H[LVWLQJ ILOH RWKHUZLVH D QHZ ILOH LV FUHDWHG bAuditLog ,I bAuditOn LV 758( LQGLFDWHV WKDW WKH VXPPDU\ H[HFXWLRQ DXGLW ORJ LV WR EH JHQHUDWHG bMSAudit ,I bAuditOn LV 758( LQGLFDWHV WKDW PDS VHWWLQJV DUH WR EH UHFRUGHG LQ WKH DXGLW ORJ bCSAudi
Chapter 6 - Platform API Structure Definitions EXEOPTS Structure 3DUW 'HVFULSWLRQ bOmitPresentation ,QGLFDWHV WKDW WKH SUHVHQWDWLRQ VHWWLQJV RI LWHPV LV WR EH LJQRUHG GXULQJ PDS H[HFXWLRQ bOmitSize ,QGLFDWHV WKDW WKH PLQLPXP VL]H RI LWHPV LQ GHOLPLWHG GDWD LV QRW WR EH FKHFNHG GXULQJ PDS H[HFXWLRQ bDeleteWorkFiles ,QGLFDWHV WKDW ZRUN ILOHV DUH WR EH GHOHWHG DIWHU PDS H[HFXWLRQ bUseMMCforWork ,QGLFDWHV WKDW ZRUN ILOHV DUH WR EH FUHDWHG XVLQJ WKH QDPH DQG ORFDWLRQ RI WKH FRPSLOHG PDS I
Chapter 6 - Platform API Structure Definitions EXEOPTS Structure 3DUW 'HVFULSWLRQ wRetryCount ,QGLFDWHV WKH QXPEHU RI UHWULHV DWWHPSWHG ZKHQ DFFHVVLQJ QRQ GDWD ILOH UHVRXUFHV wRetryInterval ,QGLFDWHV WKH LQWHUYDO LQ VHFRQGV EHWZHHQ UHWULHV wPageSizeInK ,QGLFDWHV WKH :RUN6SDFH SDJH VL]H LQ .
Chapter 6 - Platform API Structure Definitions EXEOPTS Structure Q:RUN)LOH7\SH 6HWWLQJV 7KH nWorkFileType DUJXPHQW KDV WKH IROORZLQJ VHWWLQJV &RQVWDQW 9DOXH 'HVFULSWLRQ WF_NORMAL &UHDWH ZRUN ILOHV XVLQJ WKH PDS QDPH WF_UNIQUE 8VH XQLTXH ZRUN ILOH QDPHV WF_INMEM &UHDWH ZRUN DUHD LQ PHPRU\ WF_FILE &UHDWH ZRUN ILOHV GZ)DLO)ODJV 6HWWLQJV 7KH dwFailFlags DUJXPHQW KDV WKH IROORZLQJ VHWWLQJV &RQVWDQW 9DOXH 'HVFULSWLRQ FO_OUTPUTINVALID [ )DLO RQ UHWXUQ F
Chapter 6 - Platform API Structure Definitions EXEOPTS Structure &RQVWDQW 9DOXH 'HVFULSWLRQ IW_PAGEUSECTERROR [ ,JQRUH UHWXUQ FRGH 3DJH XVDJH FRXQW HUURU IW_INPUTNOTCONSUMED [ ,JQRUH UHWXUQ FRGH ,QSXW YDOLG EXW XQNQRZQ GDWD IRXQG IW_OUTPUTINERRORWARN [ ,JQRUH UHWXUQ FRGH 2XWSXW W\SH LQ HUURU IW_OUTCONTAINSERRWARN [ ,JQRUH UHWXUQ FRGH 2XWSXW W\SH FRQWDLQV HUURUV IW_INCONTAINSERRWARN [ ,JQRUH UHWXUQ FRGH
$SSHQGL[ $ 5HWXUQ &RGHV DQG (UURU 0HVVDJHV 5HWXUQ FRGHV DQG PHVVDJHV DUH UHWXUQHG ZKHQ WKH SDUWLFXODU DFWLYLW\ FRPSOHWHV 5HWXUQ FRGHV DQG PHVVDJHV PD\ DOVR EH UHFRUGHG DV VSHFLILHG LQ WKH DXGLW ORJV WUDFH ILOHV H[HFXWLRQ VXPPDU\ ILOHV HWF 0HVVDJHV 7KH 3ODWIRUP $3, UHWXUQ FRGHV DQG PHVVDJHV PD\ UHVXOW ZKHQ DQ LQYDOLG FRPPDQG OLQH LV VSHFLILHG IRU WKH 3ODWIRUP $3, 7KH IROORZLQJ WDEOH OLVWV WKH UHWXUQ FRGHV DQG PHVVDJHV WKDW FDQ UHVXOW ZKHQ XVLQJ WKH 3ODWIRUP $3, 1RWH 7KH UHWXUQ FRGHV PDU
Appendix A - Return Codes and Error Messages Return Code Message 56 Invalid command line option –x Messages 7KH RSWLRQ LV LQYDOLG IRU WKH FRPPDQG 57 Invalid ‘W’ command line option 7KH :RUN ILOH RSWLRQ LV LQYDOLG 58 Invalid ‘B’ command line option 7KH %DWFK FORVH ILOH RSWLRQ LV LQYDOLG 59 Invalid ‘R’ command line option 7KH 5HIUHVK 5DWH RSWLRQ LV LQYDOLG 60 Invalid ‘A’ command line option 7KH $XGLW RSWLRQ LV LQYDOLG 61 Invalid ‘P’ command line option 7KH 3DJLQJ RSWLRQ LV LQYDOLG
Appendix A - Return Codes and Error Messages Return Code Message 68 Invalid ‘O’ command line option for output x Messages 7KH WDUJHW RSWLRQ LV LQYDOLG IRU RXWSXW x 7KH QXPEHU RI FKDUDFWHUV EHWZHHQ WKH VLQJOH TXRWHV WKDW UHSUHVHQW WKH RSWLRQV IRU DQ DGDSWHU H[FHHG FKDUDFWHUV LQ WKH DGDSWHU RYHUULGH 69 Invalid adapter type in command line for output x 7KH DGDSWHU LV QRW RI D NQRZQ DGDSWHU W\SH ,QFOXGHV –OMxxx ZKHUH xxx LV DQ XQNQRZQ DGDSWHU DOLDV 70 Command line memory failure 2FFXUV ZK
Appendix A - Return Codes and Error Messages Return Code Message 77 Invalid map name Messages 7KLV PHVVDJH FDQ RFFXU LQ WZR GLIIHUHQW FDVHV )LUVW WKLV PHVVDJH RFFXUV ZKHQ WKH PDS QDPH VSHFLILHG RQ WKH FRPPDQG OLQH LV PRUH WKDQ FKDUDFWHUV ORQJ $OVR WKLV PHVVDJH FDQ RFFXU ZKHQ WKHUH LV DQ HUURU LQ WKH FRPPDQG OLQH VXFK WKDW WH[W IRU DQRWKHU H[HFXWLRQ FRPPDQG LV HUURQHRXVO\ EHLQJ LQWHUSUHWHG DV WKH PDS QDPH )RU H[DPSOH LQ WKH FRPPDQG OLQH EHORZ WKH QXPEHU UHSUHVHQWLQJ WKH VL]H RI WKH HFK
,QGH[ E6RXUFH(YHQW E6WRS2Q)LUVW(UURU E7UDFH,Q E7UDFH0HPRU\ E7UDFH2Q E7UDFH2XW E8QLTXH/RJ E8QLTXH:RUN)LOH3UHIL[ E8VH00&IRU$XGLW E8VH00&IRU7UDFH E8VH00&IRU:RUN E\)ODJ E\8QXVHG A $'37B&B)B$/:$<6 $'37B&B)B$33(1' $'37B&B)B1(9(5 $'37B&B)B21&217(17 $'37B&B)B83'$7( $'37B.((3B$/:$<6 $'37B.((3B1(9(5 $'37B.
Index E 5XQ0DS 5XQ0DS8VHV,QVWDQFH GZ6L]H GZ7R/HQ GZ7UDFH)ODJV GZ7UDFH,Q(QG GZ7UDFH,Q6WDUW GZ:LOGFDUG6L]H G\QDPLF ORDG RI $3, G *HW&DUG,2V JXLGHOLQHV IRU XVH H KHDGHU ILOH E (FKR FRPPDQG RSWLRQ HQDEOLQJ HQYLURQPHQWDO GHEXJ HQDEOLQJ ILOH ORFNLQJ HQDEOLQJ 0(5&B'2B127B&+',5 HQYLURQPHQW YDULDEOHV HQYLURQPHQWDO GHEXJ HS (;,73$5$0 YDULDEOH HUURU PHVVDJHV
Index N VWUXFWXUH GHILQLWLRQV 3ODWIRUP $3, IXQFWLRQV )UHH5XQ0DS,QVWDQFH *HW&DUG,2V ,QLWLDOL]H5XQ0DS,QVWDQFH 5XQ0DS8VHV,QVWDQFH H[HFXWLRQ HQYLURQPHQW ORDGLQJ LQWR PHPRU\ XVLQJ 3ODWIRUP $3, 0$;B3$7+ 0$;B7<3(1$0( PHPFS\ PHPRU\ DOORFDWLQJ H[DPSOH RI XVLQJ PDSV LQ IUHHLQJ PDS ORDGLQJ 0(5&B$33/,&$7,21 0(5&B%8))(5 0(5&B'$7$%$6( 0(5&B'$7$),/( 0(5&B'(%8* 0(5&B'2B127B&+',5 0(5&B),/(B/2&.
Index U WHVWDSLG F 75$&(B$// 75$&(B&$5' 75$&(B5$1*( W Z%XUVW(UURU/LPLW Z&DUG Z&DUG1XP Z&OHDQXS$FWLRQ Z'DWH5HVROXWLRQ WF_FILE WF_INMEM WF_NORMAL WF_UNIQUE Z)HWFK8QLW :LQ 3ODWIRUP $3, OLEUDULHV ZLQGRZV K Z,27\SH Z0DS6XFFHVV$FWLRQ ZRUN ILOHV Z3DJH&RXQW Z3DJH6L]H,Q.
