Initiates interaction with a host application.
HCON Library
C (libg3270.a)
Pascal (libg3270p.a)
FORTRAN (libg3270f.a)
#include <g32_api.h>
g32_alloc ( as, applname, mode)
struct g32_api *as;
char *applname;
int mode;
function g32allc (var as : g32_api;
applname : stringptr;
mode : integer): integer; external;
EXTERNAL G32ALLOC
INTEGER RC, MODE, AS(9), G32ALLOC
CHARACTER* XX NAME
RC = G32ALLOC (AS, NAME, MODE)
The g32_alloc function initiates interaction with a host application and sets the API mode. The host application program is invoked by entering its name, using the 3270 operatorless interface.
If invocation of the host program is successful and the mode is API/API, control of the session is passed to the application. If the mode is API/3270, the emulator retains control of the session. The application communicates with the session by way of the 3270 operatorless interface.
The g32_alloc function may be used only after a successful open using the g32_open or g32_openx function. The g32_alloc function must be issued before using any of the message or 3270 operatorless interface functions.
HCON application programs using the Pascal language interface must include and link both the C and Pascal libraries. Applications programs using the FORTRAN language for the HCON API must include and link both the C and FORTRAN libraries.
The g32_alloc function is part of the Host Connection Program (HCON).
The g32_alloc function requires one or more adapters used to connect to a host.
CICS and VSE do not support API/API or API/API_T modes.
as | Specifies a pointer to a g32_api structure. Status information is returned in this structure. |
applname | Specifies a pointer to the name of the host application to be executed. This string should be the entire string necessary to start the application, including any necessary parameters or options. When specifying an applname parameter, place the host application name in double quotes ("Testload") or specify a pointer to a character string. |
mode | Specifies the API mode. The types of modes that can be used are contained
in the g32_api.h file and
are defined as follows:
|
as | Specifies the g32_api structure. |
applname | Specifies a stringptr containing the name of the host application to be executed. This string should be the entire string necessary to start the host application, including any necessary parameters and options. A null application name is valid in 3270 mode. |
mode | Specifies the mode desired for the session. |
AS | Specifies the g32_api equivalent structure as an array of integers. |
NAME | Specifies the name of the application that is to execute on the host. |
MODE | Specifies the desired mode for the API. |
0 | Indicates successful completion. |
-1 | Indicates an error has occurred. |
The following example illustrates the use of the g32_alloc function in C language:
#include <g32_api.h> /* API include file */
main ()
{
struct g32_api *as, asx; /* API status */
int session_mode = MODE_API /* api session mode. Other
modes are MODE_API_T
and MODE_3270 */
char appl_name [20] /* name of the application to
run on the host */
int return; /* return code */
.
.
.
strcpy (appl_name, "APITESTN"); /* name of host application */
return = g32_alloc(as, appl_name, session_mode);
.
.
.
return = g32_dealloc(as);
.
.
.
/usr/include/g32_api.h | Contains data structures and associated symbol definitions. |
/usr/include/g32const.inc | Defines Pascal API constants. |
/usr/include/g32hfile.inc | Defines Pascal API external definitions. |
/usr/include/g32types.inc | Defines Pascal API data types. |