HOME PUBLICATIONS NEWS EVENTS BUYER'S GUIDE FORUMS VIDEOS POPULAR ARCHIVE STORE Remember me Forgot Password?

| Register

Analysis App Software Career Database Internet Networking OP Systems Printing Programming Security System Admin TechTips WebSphere Analysis of News Events Commentary Business Intelligence Business Management Collaboration Content Management Customer Relationship ERP/Financial General High Availability IBM Managed Services Microsoft General Data Warehousing DB2 JDBC Microsoft Access Microsoft ODBC MySQL Oracle SQL General Portals

Protocols Telephony Web Conferencing Emulation General Wireless/WiFi i5/OS Linux/Open Source Microsoft UNIX/AIX General APIs Change Management CL General Java RPG Scripting SQL Visual Basic Web Languages Compliance/Privacy General i5/OS Microsoft General Performance Monitoring & Tuning APIs Career CL Collaboration Database HA/DR i5/OS Internet Java Linux MS Networking Printing Programming RPG Scripting Security SQL Sys Admin Web Languages WebSphere General Systems Management

The Distributed Program APIs Written by Craig Pelkie Friday, 31 March 1995

With no fanfare whatsoever, IBM introduced a major new API set for the Windows c lient of Client Access/400. This set, collectively known as the Distributed Prog ram APIs, is available with the System Object Access function. Simply stated, th e APIs let you develop programs on the PC that can directly call programs on the AS/400, passing and receiving parameter values. This is a radical innovation, and potentially will help you develop client/ serv er programs much more quickly than using other APIs. Because you can directly ca ll an AS/400 program, you don t need to code special communications code, as with the APPC APIs, or include data queue handling when using the data queue APIs. In fact, if you have AS/400 functions already split out into subprograms for example , a tax calculation routine that is in a separate program you should be able to ca ll those programs directly from your PC program. The Distributed Program APIs ca n help you create client/server programs more quickly than other methods because you can use the AS/400 programs that you already have.

How to Get the APIs You get the Windows DLL that provides the API functions when you install System Object Access (SOA). You can order SOA as a PTF package (SF21273 for licensed pr ogram 5763-XC1), or install SOA from the Client Access/400 refresh that is sched uled for release soon. If you order the PTF, you need to specify DELIVERY(*ANY). The PTF package will be sent to you on tape because the package is too large to be sent over ECS. (See the May/June 1995 issue of PCSE for a review of other fu nctions in SOA, System Object Access - Application or API? ) When you install SOA, a subdirectory called SOASPGMS is created in your CAWIN di rectory. The SOASPGMS directory contains sample programs and source

code for running the SOA programs. The file that you want to look at is EHNDPW.H , the C header file for the Distributed Program-Windows APIs. The header file co ntains some documentation for the APIs, constants used with the APIs, and functi on declarations for each of the APIs. In addition to the header file, file EHNDPW.DLL is installed in the CAWIN direct ory. The DLL file contains the executable code for each of the APIs. The DLL can be used with any PC language that supports the C calling convention. The APIs i n EHNDPW.DLL can only be used by Windows programs.

API Functions Provided There are 25 user-accessible functions within EHNDPW.DLL. These functions are di vided into three groups. System Functions are used to create a connection between the PC program and the AS/400. When you use the system functions, you start a server job on the AS/400 that processes your program call requests. You also end the server job using a s ystem function API. The Program Functions group contains APIs to define the program that will be cal led, work with parameters for the program, call the program, and get information about the program and parameters. Finally, the Message Functions group helps you get messages and information abou t messages that are sent as a result of errors when calling the program. As with any API set, it makes sense to learn about the APIs by looking at how th ey re used, rather than by proceeding through the APIs alphabetically. There is a specific sequence that you ll need to use when calling a program with the APIs. Yo u ll also find that you only need to use a subset of the APIs to get started.

Getting Started with the APIs To get started with the APIs, you ll first want to print file EHNDPW.H, the C head er file. Even if you plan to use a PC language other than C, you ll need to examin e this file to learn about the APIs, the parameters used on the functions, and t he return code values that you might encounter. Later in this article, I ll tell y ou how to get an equivalent file of function declarations that you can use with Visual Basic. EHNDPW.H starts with notes about how the APIs are used. If you are accustomed to working with PC languages, the concepts and program flow will probably be easy to grasp. However, if most of your experience is as an RPG programmer, you might find it difficult, at first, to understand how the APIs are used. With an RPG p rogram, you customarily include a CALL statement, followed by PARM statements. T he Distributed Program APIs define the parameters first, then call the program. I ll explain this in more detail later. After the initial documentation, EHNDPW.H continues with definitions for constan ts. The first set of constants is used to define the maximum number of parameter s, and the parameter types. You can call an AS/400 with up to 25 parameters. Parameter types can be defined as input, output, or input/output. These types pr ovide options that are different from the way an AS/400 programmer customarily u ses parameters. In an RPG, COBOL, or CL program, all parameters are input/output , as values can be passed and returned through any parameter (i.e., if you call an AS/400 program from another AS/400 program, the called program can change a p

arameter, and the change is reflected back to the caller).

The input and output parameter types are used extensively with the APIs themselv es. An input parameter is passed from the calling program to the called program. Any changes to the parameter are not returned to the caller. An output paramete r is in the parameter list of the calling program; however, any value that you s et in the calling program is not passed to the called program. The called progra m can change the value of the output parameter. The changed value is available t o the calling program upon return from the called program. To call existing AS/400 programs, you might want to consider defining the parame ters as input/output, as that provides the same type of parameter usage availabl e with AS/400 languages. You ll need to examine existing code carefully to see if you can define parameters as simple input or output parameters. The next set of constants in EHNDPW.H is used to define message types. These con stants are used with the Message Functions API group. For example, you can test a message to determine if it is a completion, diagnostic, notify, or escape mess age. The final set of constants define return codes from the API functions. These are in four general groups: the OK return code, meaning that the API functioned cor rectly; communications return codes (e.g., no connection to system); program err ors (e.g., program not found, too many/ too few parameters); and environment err ors (e.g., invalid window, system, or program handle). As with any API, you shou ld, at a minimum, check for the OK return code. If the return code is not OK, yo u can then go to a generic error handling routine, or you can branch to specific error handling depending on the type of return code.

The Function Declarations After the constants, EHNDPW.H begins the function declarations. The declarations are listed by function group (i.e., system, program, message), and roughly in o rder by usage within the groups. Each API function declaration starts with a synopsis that includes the name of t he API, a brief description of it, then a list of the parameters used with the A PI. Although the synopsis includes a reference for return codes, none of the API s currently have any documented return codes. You should be able to examine the return code constants and determine which ones will apply to an API. You can als o test each API individually to discover the return codes that you might encount er (e.g., call a nonexistent program to discover the return code that you get in that situation). The function declarations are standard C syntax and formatting. Windows conventi ons are used for the data type and variable names.

All of the Distributed Program functions start with the character string EHNDP_ . T he second part of the function name is descriptive of the function. For example, the EHNDP_StartSys API is used to start the conversation with the AS/400. If you work with C, you should find the function declarations to be straightforw ard. But even if you re unfamiliar with C, or don t use C as your primary programmin g language, you should spend some time reading through the declarations. You ll wa nt to know the functions that are available, their names, and the parameters use d with each function.

The Distributed Program API Tester Program I created a test program in Visual Basic to learn about the Distributed Program APIs. Figure 1 shows the dialog that is presented when the program is run. The p rogram uses six command buttons to run Distributed Program functions. The Visual Basic

program calls an AS/400 CL program, passing parameters to it. The CL program sen ds a message to the QSYSOPR message queue, displaying the parameters. The CL pro gram finishes by moving a value into a parameter. The return value is obtained w ith a Distributed Program API and placed into the message list box shown in the figure. The code for these programs is too long to include with this article, bu t you can get it with the Visual Basic function declaration file. Even without t he code, we can examine the flow of the Tester program, which I feel is represen tative of the flow that you would use for production programs. The Tester demons trates the initialization and cleanup work you ll need to do, and also how to defi ne parameters, put values into them, call the AS/400 program, and extract the va lue for returned parameters. Before stepping through the details of the program, we need to get an overview o f processing flow, as it relates to using the Distributed Program APIs.

Sequence and Flow of the APIs I mentioned earlier that using the Distributed Program APIs is not quite the sam e as the AS/400 CALL/PARM construct. There are several additional steps that you need to take before issuing the program call. You need those additional steps b ecause you must create the proper environment for the program call. You then nee d to provide details about each of the parameters you re going to use. After actua lly calling the program, you retrieve the parameters that contain return values. When you re finished, you close the environment that you created for the APIs. Before you can use the Distributed Program APIs, you need a router connection to the AS/400 where the program that you want to call is located. Your first step with the Distributed Program APIs is to start a connection to the system. You th

en create a program, which means that you identify the program you re going to call. After creating the program, you can add up to 25 parameters to it. As with any AS/400 program, the parameters must match those on the called program. At that point, you can call the AS/400 program. Assuming that you ve correctly def ined the parameters and have a working connection, the AS/400 program will run. The called program must be batch oriented; you cannot call an AS/400 program tha t uses display file I/O. When the AS/400 program returns or ends, you then call Distributed Program APIs to retrieve the parameter values. Unlike standard AS/400 programs, where values for all of the parameters are available to the calling program when the called p rogram returns, you specifically have to retrieve the value from each parameter in which you re interested. At this point, you can call the same or another program. You already have the co nnection environment, so you don t need to start the system again. If you re calling a different program, you need to create the program and add parameters to it. I f you re recalling a program that you ve already created and added parameters to, yo u can use an API to set the value of the parameters for a subsequent call. When you re done working with the AS/400 programs, you delete the program, which rem oves it from your PC environment. Finally, you stop the system, which means that your connection with the AS/400 is dropped (not the router, just the Distribute d Program connection to the server program). At any point during your calling sequence, you may need to use the APIs that obt ain information about the environment. After calling an API, you will need to ch eck the return code. If the call was unsuccessful, you may need to call the mess age handling

APIs to retrieve the AS/400 error messages. The message handling APIs provide fu nctions equivalent to the program message queue handling operations on the AS/40 0. I ll explain what happens when you click each of the command buttons on the Tester . When you obtain the source code and run the program, you ll find it useful to st ep through the program and set breakpoints.

The Start System Function Before you can call an AS/400 program with the Distributed Program API, you have to start a connection to the AS/400. This connection is between your PC program and an AS/400 server job. This connection presumes that you have an active rout er connection to the AS/400.

If you attempt to start the program connection without having an active router s ession, the start attempt fails. You start the program connection with the EHNDP_StartSys (StartSys) API. Figure 2 shows the details of this API. StartSys uses four parameters. The first, hWnd, is the handle to the window that the program is associated with. This is standa rd Windows programming practice. hWnd is the first parameter of all of the Distr ibuted Programming APIs, so I won t describe it again from this point on. The second parameter is the name of the system with which you want to start the connection. This is one of the systems to which you have a router connection. As with other Client Access APIs, you can pass a null value for this parameter, in which case the default system is used. The third parameter is the application name. This is supposed to be a unique ide ntifier for the application you re starting. A null value is allowed for this para meter. The application name is not used in any of the other Distributed Program APIs, so its purpose is unclear. The last parameter is a return value, the handle to the system. This is a very i mportant value, as it is used with other Distributed Program APIs to point the A PIs to the correct system. For example, if you start connections to two systems within the same PC program, you need to use StartSys for each system. You ll get a unique handle for each system, which then identifies that system. As with any h andle, you must never alter its value. You just use the value that is passed bac k from the API. The value has no meaning as far as your application is concerned ; it is used internally by the APIs. When you use StartSys, two jobs are started in the QCMN subsystem. The first job starts program QLZPSERV. I couldn t determine the functions performed by this job , in relation to the Distributed Program APIs. The second QCMN job starts progra m QIWS/QZRCSRVR. This program is the actual server processor, which handles Dist ributed Program requests from your PC program. This job uses ICF file QIWS/QCZRC ICF to communicate with the PC. Examining this job shows that APPC is being used to communicate from the PC program to the AS/400 program. However, we re insulate d from the low-level APPC programming required for communications between the tw o machines. This is one of the main advantages of the Distributed Program APIs. If you used a null value for the system name on StartSys, you can find out the n ame of the system used with the EHNDP_GetSysName (GetSysName) API. The API is de scribed in Figure 3. If you explicitly passed a system name, there would be no p oint to call this API because you d already know the name of the system. But if yo u re creating general-purpose programs that might run with different AS/400s, you might need to use the null system name value on StartSys, then use GetSysName to get the default

name. You could also use EHNAPPC_GetDefaultSystem from the APPC API, but GetSysN ame ensures that you get the system name that applies to the StartSys API usage.

GetSysName uses three parameters. The second is the handle to the system that wa s returned from StartSys. The third is the name of the system that the connectio n was started to. Figure 1 shows the result of clicking the Start System command button. The messa ge list box at the top of the figure contains messages that I formatted after ca lling the APIs. After calling each API, I check for a return code of EHNDP_OK, m eaning that the API completed successfully. If the return code is not OK, I go t o an error message formatting routine. For some APIs, such as the StartSys API, I include additional information on normal completion. In this example, I m displa ying the hex value of the system handle returned by StartSys. I include a separa tor line between each API, as shown in the figure. After clicking each command b utton, you can review the additional messages by scrolling through the message l ist box. I can t show you the entire sequence of messages in the list box, so I wo n t describe them any more in this article. Just be aware of the function when you run the sample program.

The Create Program Function Contrary to what you make think from its name, the EHNDP_CreatePgm (CreatePgm) A PI does not create a program on the AS/400 in the way that a CRTxxxPGM command d oes. Instead, the CreatePgm API creates a program object in your PC memory. That object is used to identify the actual program that you want to call on the AS/4 00, and serves as a connection between your PC and the actual AS/400 program. Fi gure 4 shows the parameters used with CreatePgm. If most of your programming experience is in the AS/400 environment, you ll want t o take the time to be clear on how the terminology used with this API differs fr om the AS/400 terminology. The API uses the verb create and the noun object, which A S/400 programmers instinctively associate with a program object being created fr om source. As you can see from Figure 4, what you re really creating with this API is a handl e to a named program. This is all done in the PC memory. When you run this API, there is no communication flow to the AS/400. The API does not verify that you s upplied a valid library and program name. If you used incorrect values (e.g., yo u specified a program name that doesn t exist), you won t find out about it until yo u actually call the program. You need to run this API to get the handle assignment. After getting the handle to the program, you ll need to add parameters to the program using the handle. Fin ally, you can call the program. I haven t yet experimented with special or NULL values for the library name parame ter. The QCMN communications entry that handles the program evoke request when t he program is called specifies a default user value of *SYS. The user profile us ed to start the router is associated with the server job that processes the requ est, so the library list for the user is available to the job. I presume that sp ecial values like *LIBL are supported for the library name parameter on this API .

After calling the CreatePgm API, you have a handle to the system where the progr am is located, and a handle to the program object that you re going to call. That takes care of establishing the environment for the program. You now need to add parameters to the program before calling it.

The Add Parameter Function Unlike the AS/400 CALL/PARM construct, you define your parameters before issuing the call. You define parameters with the EHNDP_AddParm (AddParm) API, shown in Figure 5. When you use AddParm, what you re really doing is reserving space in your PC memor y. This space is simply a sequence of 1 to n bytes. You specify how many bytes t o reserve for the parameter. When you use AddParm, a pointer to that space is se t, and the parameter count is incremented. The pointers and parameter count are associated with the program that you re going to call, by the program handle value that was returned in CreatePgm. AddParm uses a parameter to specify the type of parameter, which has nothing to do with the field characteristics (string or numeric and length). The type of pa rameter is input, output, or input/output. If you re an AS/400 programmer, you ll pr obably be most comfortable defining all of the parameters as input/output, as th at provides an equivalent to how AS/400 programs call each other. As you become more familiar with the Distributed Program APIs and processes, you might want to refine your parameter type usage. This is actually a pretty interesting process, under the covers. The way this pr ocess works, it appears that there is a mechanism within the AS/400 server to ad d parameters dynamically to a program call. This differs from the usual AS/400 p rogramming practice, where you hard-code the number of parameters into your AS/4 00 source programs. Now, for sure, the AS/400 has always had such a built-in par ameter handling mechanism because it has to resolve the number of parameters whe n one AS/400 program calls another. Here, we have access to this parameter list building process. Unlike AS/400 programs, you don t specify the type of parameter, but only the leng th of the parameter. For character string fields, you can simply use the length of the string. For numeric fields, you ll have to be careful to match the expected parameter in the AS/400 program. For packed fields, which are the default in CL programs and RPG programs unless defined differently, you need to calculate the number of bytes required to hold the field and the sign half-byte. For example, if a CL program parameter variable is DEC(5,0), you ll need a parameter length of 3 on the AddParm API (two and a half bytes used for the five digits, one-half b yte for the sign). If the parameter is DEC(6,0), you need a parameter length of 4.

If you ve defined the numeric field explicitly as zoned or binary, then you need t o specify the number of bytes required to hold the field. In my testing, I found numeric parameters to be particularly troublesome. This i s because of the parameter length consideration, and also because the values nee d to be converted from ASCII to packed, zoned, or binary, then back, when return ing to the PC program. The conversion functions are in the Data Transform API (E HNDT). They are not particularly easy to use in Visual Basic, as you need to wor k with pointers to the values. The sample program includes an example of ASCII-t o-Packed conversion. As with any call to an AS/400 program, you must supply the right number of param eters, and values for numeric parameters must be valid. For example, if your AS/ 400 has three parameters, you can t just concatenate all of the values in your PC program and pass one parameter that s as long as all three. You need to pass three corresponding parameters. If you don t pass valid numeric values, you ll get MCH-ty pe error messages when your called program on the AS/400 references the paramete r. Based on the experience I had with the Distributed Program APIs, you ll want a program like Tester to experiment with parameter passing.

The Call Program Function After defining your parameters, you use the EHNDP_CallPgm (CallPgm) API to actua lly call the AS/400 program from your PC program. Looking at the function defini tion in Figure 6, you can see that this API is almost anticlimactic. That s becaus e you ve done all of the set-up work before issuing the call. The API simply refer ences the handles of the system and the program that were created earlier. The p arameter list is from the AddParm API calls that you did before using this API. As with AS/400 program-to-program calls, this is where the action and the proble ms start. You ll run into the usual problems, such as the program not being found, authority problems, incorrect parameters, and so on. Upon return to your PC pro gram, you absolutely must check the return code from the CallPgm API before you even think of using any other Distributed Program APIs. If the return code is an ything other than EHNDP_OK, you had a problem. You can use the message function APIs to retrieve the messages sent from the AS/400, and possibly determine what the cause of the failure was (chances are that the system operator will also get messages on the AS/400, and you ll have a job log from the failed job to work wit h). The Distributed Program APIs include two APIs that relate to the call mode of the program. The default call mode is synchronous, meaning that while the called AS/ 400 program is processing, your PC program is locked. The EHNDP_SetCallMode API lets you set the call mode to asynchronous, meaning that you can call the AS/400 program, then resume your PC program while waiting for the called program to re turn. The EHNDP_GetCallMode API retrieves a value that lets you determine the cu rrent mode being used.

I didn t see any documentation about how this feature works, but I suspect that Wi ndows call-back processing is used. If so, Visual Basic programs are limited to synchronous mode, unless third-party VBXs or custom controls that provide call-b ack support are obtained. I did not test the SetCallMode API; all of my tests we re done with the default, synchronous call mode. My feeling is that this should not present too much of a problem. If you re going to use existing AS/400 modules, chances are that those modules are already worki ng with interactive programs. In that case, when you call the module from an AS/ 400 program, you are, in effect, working in synchronous mode anyway. Your respon se time should be comparable to an AS/400-to-AS/400 program call, meaning that i t should be tolerable, especially after the first call. If you find response tim e of synchronous calls to be an issue, and you re working with Visual Basic (no ca ll-back support), you might need to consider alternative methods of submitting wor k and then checking for a response, such as data queues.

The Get Parm API At this point, you have all of the APIs you need to call an AS/400 program and p ass parameters to it. Although useful, you probably also want to receive paramet ers back. To do that, you ll need to use the EHNDP_GetParm (GetParm) API, shown in Figure 7. You need to call GetParm for every parameter for which you want to retrieve a va lue. That s because you don t have a parameter list, as in an RPG program; you can t j ust refer to values. Even though you added the parameter earlier with the AddPar m API, you need to use GetParm. Think about what s happening: the AS/400 program h as returned, and written the parameter values out. You didn t directly call the AS /400 program; you used the server program on the AS/400 as your intermediary.

Because the server program doesn t have hard-coded knowledge of how many parameter s you re working with, you have to request those parameters from the server with t he GetParm API. When you use GetParm, the parameter values are retrieved from th e server program and written to your PC memory, where you can then reference the m. GetParm is tricky to use, especially in Visual Basic, because the returned param eter is a pointer to a pointer. You ll need to use either the EHNDT_MemCopy API or the Windows lstrcpy function to copy the returned parameter from the memory loc ation indicated by the pointer to a buffer (string) that you can use in Visual B asic. Another consideration with GetParm is that you reference the parameter you want by relative order in the parameter list. You need to refer to the parameter by n umber because there are no field names associated with the returned parameter li st, as in an RPG program. The list is zero-based, meaning that the first paramet er is identified as parameter zero, the second parameter in the list is identifi ed as parameter one, and so on.

Another API that you might need to use is EHNDP_GetParmCount (GetParmCount), sho wn in Figure 8. This API returns a value that indicates the number of parameters in the list. Using GetParmCount, you might be able to create a generic paramete r retrieval routine in your PC program, looping through GetParm for the number o f parameters from GetParmCount. The alternative is simply hard-coding GetParm co de for each parameter. After you retrieve the parameters that you can work with (in Visual Basic you ha ve to move them to a buffer), you ll need to do some additional work before you ca n use the value. For character string values, you ll need to do an EBCDIC to ASCII translation. For numeric parameters, you ll need to use the appropriate Data Tran sform API to convert from packed, zoned, or binary to an ASCII numeric value. Th is can be tedious and error-prone coding. You ll probably want to run some test ca ses, then create wrapper functions that you can simply include in your productio n programs.

The Delete Program API When you re done calling the AS/400 program, you should call the EHNDP_DeletePgm ( DeletePgm) API to remove the program object from your PC memory. Doing so will f ree up the memory for other purposes. The DeletePgm API does not delete the prog ram object on the AS/400. Figure 9 shows the DeletePgm API parameters. After you call this API, you can no longer use the CallPgm API for the same program handle. You would have to use C reatePgm again to create a new handle and program object. You can call DeletePgm at any point after creating the program handle. For examp le, if your application only needs to call an AS/400 program once for initializa tion purposes, there s no point to keeping the program object constructs in PC mem ory after the initialization.

The Stop System API When you re done calling AS/400 programs from your PC program, you ll want to call t he EHNDP_StopSys (StopSys) API, shown in Figure 10. Calling this API terminates the conversation with the server program on the AS/400. If you neglect to call t his API, the server program remains active. After calling this API, the handle to the system that was created in the StartSy s API is no longer usable. If you want to call AS/400 programs again, you need t o go through the entire process, starting with StartSys.

If you started conversations to multiple systems, you need to run StopSys for ea ch system. Conversely, you can use StopSys for one system, but continue to use a ctive conversations to other systems.

Other APIs In this article, I have not shown or described many other APIs. Figure 11 shows the names of those APIs and briefly describes them. In the Tester program, I use several of the Message Function APIs to retrieve er ror messages from the AS/400.

Distributed Program Versus Other Techniques As exciting as the Distributed Program API suite is, you need to consider where it fits in with other Client Access/400 APIs and techniques. It is true that thi s suite provides the equivalent function that AS/400 programmers have used for y ears: the capability of calling one program from another, and passing parameters between the programs. However, that technique has always had built-in limitatio ns. For example, say that you want to create a server program that you ll call to read records from a file. You don t know how many records each call will return; it co uld be from zero to many. It s tricky to write such a server, and fill up an arbit rary buffer with records. I know; I ve created a system that uses such servers. In this case, it might be better to use an APPC or a CPI-C program, or a data queu es program, to receive the file processing request, then fill a buffer that is e xternal to the program. For example, APPC and CPI-C send operations will fill a co mmunications buffer that the system manages. With data queues, you simply write a data queue entry for each record. The system manages the buffer. Your receivin g program has a far easier job because it can simply retrieve one entry at a tim e from the buffer or queue. On the other hand, you probably have a number of routines already coded that you v e been using for years in your production systems. If you ve been careful to creat e stand-alone modules, you can probably call those modules from your Windows pro grams. This will help you quickly develop a Windows equivalent to the AS/400 pro gram because you don t have to recreate the logic that is available in the existin g modules. There is no limitation on using any of these techniques exclusively in a program . You might find that you use both the Data Queues and the Distributed Program A PIs in the same program. The Distributed Program API is certainly a welcome addi tion, but it does not render the existing techniques obsolete.

The Tester Program

The Tester program, as illustrated in Figure 1 and described in this article, in cludes the Visual Basic code for the form and a Visual Basic equivalent of the E HNDPW.H file, in which I provide function declares for the Distributed Program A PIs. This code is available on the Midrange Computing BBS in the AS/400 file download area, or directly from me. The BBS number is listed on page 2 of this issue of PCSE. If you prefer, you can send your request for the code to me at the address shown below. You ll need to include a self-addressed, stamped envelope with 55 cents po stage for U.S. addresses (foreign subscribers, please determine the correct post age and prestamp your envelope with U.S. postage). You ll also need to include one 3.5-inch

blank, IBM-formatted diskette. Requests without postage or the diskette will not be processed.

Acknowledgments I especially want to thank Mike Young and his developers at the IBM Rochester la b. Mike called me about some other issues, and during our conversation, I mentio ned that I was working with the Distributed Program APIs. At the time, I encount ered what I thought might be a bug in the DLL. The problem was with the EHNDP_Ge tParm API. Mike confirmed the problem and sent an updated version of the DLL to me. He also indicated that this correction will be made available as a PTF at so me point. The version of EHNDPW.DLL that I have is dated 6/27/95. The version di stributed with SOA is 3/30/95. If you install the SOA code and have that version of the file, you will encounter the bug. I cannot provide the updated version o f the DLL, so you will have to monitor either the IBM PTF list (SF97310), or che ck future issues of PCSE for notification of the public availability of the fix. Finally, I want to thank Daniel Appleman of Desaware in San Jose, California. Da niel helped me with the code required to reference a parameter on the EHNDP_GetP arm API. Daniel specializes in Visual Basic API programming. In addition to crea ting tools for Visual Basic, he wrote the definitive book on accessing Windows D LLs from Visual Basic. I ve listed the book title below. If you re going to work wit h Visual Basic and the Client Access/400 or PC Support APIs, you will find this book to be an outstanding resource.

References Visual Basic Programmer s Guide to the Windows API, Daniel Appleman, Ziff- Davis P ress, 1993 (ISBN 1-56276-073-4).

Tester Diskette Address Craig Pelkie PO Box 1473 Valley Center, CA 92082-1473

Figure 1: The Distributed Program API Tester Dialog Purpose Start a conversation with an AS/400. If successful, a handle for the con versation is returned. Parameters hWnd Handle to the window. lpszSystemName ASCIIZ string containing the system na me, or NULL for default system. lpszAppName ASCIIZ string of unique application identifier. Can by NULL. lphSystem Handle to the conversation for the system. Figure 2: The EHNDP_StartSys API Purpose Get the name of the system used when starting the connection with EHNDP_StartSys. Parameters hWnd Handle to the window. hSystem Handle to the system. This is from the lphSys tem parameter on EHNDP_StartSys. lpszSystemName 9-character buffer where the nam e of the system will be written (8-character system name, 1 space for terminating NULL character ). Figure 3: The EHNDP_GetSysName API Purpose Create a program object (handle to the program) for a given library and program name. Parameters hWnd Handle to the window. lpszProgramName ASCIIZ string containing the name of the AS/400

program to be called. lpszLibraryName ASCIIZ string containing the name of the A S/400 library where the program is located. lphProgram Handle to the program object. Figure 4: The EHNDP_CreatePgm API Purpose Add a parameter to the program identified by the program handle. Use thi s API for each parameter to be passed. Parameters are added to the program in the order that this API is called. Parameters hWnd Handle to the window. hProgram Handle to the program object (from EHNDP_Cre atePgm). uiType The type of parameter. This can be EHNDP_INPUT, EHNDP_OUTPUT, or EHNDP_INOUT (see EHNDPW.H for definitions of those constants). ulLength The leng th of the parameter. lpParameter Pointer to the buffer where the parameter value is located for INPUT or INOUT parameter types; or pointer to buffer where parameter value will be return ed for OUTPUT or INOUT parameter types. Figure 5: The EHNDP_AddParm API Purpose Calls the program identified by the program handle. The return code indi cates the success or failure of the call. Parameters hWnd Handle to the window. hSystem Handle to the system from EHNDP_StartSys. hPr ogram Handle to the program object (from EHNDP_CreatePgm). Figure 6: The EHNDP_CallPgm API Purpose Retrieve the parameter identified by the index. You have to call this AP I for every parameter for which you want to retrieve a value. Parameters

hWnd Handle to the window. hProgram Handle to the program object (from EHNDP_Cre atePgm). uiIndex Number of the parameter to retrieve. Parameter count starts at 0. lpuiType Pointer to the type of parameter (EHNDP_INPUT, EHNDP_OUTPUT, EHNDP_INOUT). length The length of the parameter in bytes. lplpParameter Pointer to a pointer that indicates where the parameter value is written. Figure 7: The EHNDP_GetParm API Purpose Get the number of parameters for the program identified by the program h andle. Parameters hWnd Handle to the window. hProgram Handle to the program object (from EHNDP_CreatePgm). lpusCount Unsigned integer containing the number of parameters. Figure 8: The EHNDP_GetParmCount API Purpose Delete the program object (construct in PC memory) identified by the han dle. Parameters hWnd Handle to the window. hProgram Handle to the program object (from EHNDP_Cre atePgm). Figure 9: The EHNDP_DeletePgm API

Purpose Stop a conversation with the system identified by the handle. Parameters hWnd Handle to the window. hSystem Handle to the system that was created by the EHNDP_StartSys API. Figure 10: The EHNDP_StopSys API API Description EHNDP_GetPgmName Get the name of the program used on the EHNDP_CreatePgm API. EH

NDP_GetLibName Get the name of the library used on the EHNDP_CreatePgm API. EHND P_SetParm Set the parameter value identified by the index. Use this to change a parameter value, after using the EHNDP_AddParm API. EHNDP_SetPgmName Set the nam e of the program. EHNDP_SetLibName Set the name of the library. EHNDP_GetMsgCount Get the number o f messages returned by the AS/400. EHNDP_GetMsgId Get the message ID of the mess age returned from the AS/400. EHNDP_GetMsgType Get the type of message returned from the AS/400. EHNDP_GetMsgLen Get the length of the message returned from the AS/400. EHNDP_GetMsgSev Get the message severity of the message returned from t he AS/400. EHNDP_GetMsgFile Get the message file name and library for the messag e returned from the AS/400. EHNDP_GetMsgText Get the message text returned from the AS/400. EHNDP_Ge tSubstTextLen Get the length of the substitution text for the message returned f rom the AS/400. EHNDP_GetSubstText Get the substitution text for the message returned fr om the AS/400. Figure 11: Other Distributed Program APIs

Last Updated ( Friday, 31 March 1995 ) No Comments Have Been Posted. User Rating: / 0 PoorBest < Prev Next > [ Back ] MOST POPULAR ARTICLES BOOKS FORUMS SEARCHES Picking the Right Partner for RPG Is There a Rich Client in Your Future? TechTip: Simplify Report Development with DB2 Web Query Business Views Book Review: JavaScript for the Business Developer The API Corner: Finding All *SRVPGMs on the System As IBM Reaches Out to Business Partners, Will They Reach Back to IBM? Best Practices for Selecting Application Development Tools Laptop Technology Comes of Age Will Google's Android Cure iPhone-Envy? Boost Efficiency in the Real World with Electronic Forms and Documents Top 10 Best-Selling Titles for August 2008 System i Disaster Recovery Planning HTML for the Business Developer The Modern RPG IV Language, Fourth Edition Free-Format RPG IV IBM System i APIs at Work, Second Edition SQL for eServer i5 and iSeries

Subfiles in RPG IV JavaScript for the Business Developer Qshell for iSeries DB2 9 for Linux, UNIX, and Windows Database Administration Certification Study G uide How to display many subfile columns (461 views) Picking the Right Partner for RPG (302 views) Printing Bar Codes in an internal output spec's (167 views) DB2 Web query vs SEQUEL (69 views) ANSI to UTF-8 on IFS (63 views) Schedule Announced for Conference & Workshops on SOA, SaaS, Virtualisation & ECM (49 views) Schedule Announced for Conference & Workshops on SOA, SaaS, Virtualisation & ECM (31 views) 1. DB2 web query 2. display PDF 3. seiden 4. pdf 5. web services 6. Subfiles 7. subfile 8. spooled files and pdf 9. Chris Smith 10. green

MC-STORE.COM Home | Publications | News | Events | Buyer's Guide | | Popular | Archive | Store Forums | Videos

Copyright 2008 MC Press Online, LP | Privacy Policy | Search | RSS | FAQ | Contact Us | Write For Us | Advertise | Site Map