g32_alloc Function

AIX Version 4.3 Communications Technical Reference, Volume 1

g32_alloc Function

Purpose

Initiates interaction with a host application.

Libraries

HCON Library

C (libg3270.a)

Pascal (libg3270p.a)

FORTRAN (libg3270f.a)

C Syntax

#include <g32_api.h>

g32_alloc (as, applname, mode)

struct g32_api *as;

char *applname;

int mode;

Pascal Syntax

function g32allc (var as : g32_api;
   applname : stringptr;
   mode : integer): integer; external;

FORTRAN Syntax

EXTERNAL G32ALLOC

INTEGER RC, MODE, AS(9), G32ALLOC

CHARACTER* XX NAME

RC = G32ALLOC (AS, NAME, MODE)

Description

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.

C Parameters

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:

MODE_3270	The API/3270 mode lets local system applications act like a 3270 operatorless interface. Applications in this mode use the 3270 operatorless interface to communicate with the host application. In API/3270 mode, if the value of the applname parameter is a null pointer, no host application is started.
MODE_API	The API/API mode is a private protocol for communicating with host applications that assume they are communicating with a program. Applications in this mode use the message interface to communicate with host applications using the host API. The API program must use HCON's API and must have a corresponding host API program that uses HCON's host API for the programs to communicate. Note: When a session is in this mode, all activity to the screen is stopped until this mode is exited. API/3270 mode functions cannot be used while in the API/API mode. The keyboard is locked.
MODE_API_T	The API_T mode is the same as the MODE_API type except this mode translates messages received from the host from EBCDIC to ASCII, and translates messages sent to the host from ASCII to EBCDIC. The translation tables used are determined by the language characteristic in the HCON session profile. Note: A host application started in API/API or API/API_T mode must issue a G32ALLOC function as the API waits for an acknowledgment from the host application, when starting an API/API mode session.

Pascal Parameters

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.

FORTRAN Parameters

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.

Return Values

0	Indicates successful completion.
-1	Indicates an error has occurred. The `errcode` field in the g32_api structure is set to an error code identifying the error. The `xerrinfo` field can be set to give more information about the error.

Examples

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);
.
.
.

Implementation Specifics

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.

Files

/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.