g32_open Function

Purpose

Attaches to a session. If the session does not exist, the session is started.

Libraries

HCON Library

C (libg3270.a)

Pascal (libg3270p.a)

FORTRAN (libg3270f.a)

C Syntax

#include <g32_api.h>

g32_open (as, flag, uid, pw, sessionname)

struct g32_api *as;

int flag;

char * uid;

char * pw;

char * sessionname;

Pascal Syntax

function g32open(var as : g32_api; flag : integer;

 uid : stringptr;

 pw : stringptr;

 sessionname : stringptr) : integer; external;

FORTRAN Syntax

INTEGER G32OPEN, RC, AS(9), FLAG

EXTERNAL G32OPEN

CHARACTER*XX  UID, PW, SESSIONNAME

RC = G32OPEN(AS, FLAG, UID, PW, SESSIONNAME)

Description

The g32_open function attaches to a session with the host. If the session does not exist, the session is started automatically. The user is logged on to the host if requested. This function is a subset of the capability provided by the g32_openx function. An application program must call the g32_open or g32_openx function before calling any other API function. If an API application is running implicitly, an automatic login is performed.

The g32_open function can be nested for multiple opens as long as a distinct as structure is created and passed to each open. Corresponding API functions will map to each open session according to the as structure passed to each.

HCON application programs using the Pascal language interface must include and link both the C and Pascal libraries. Application programs using the FORTRAN language for the HCON API must include and link both the C and FORTRAN libraries.

C Parameters

userid, node_id, trace, time=n,...

Pascal Parameters

FORTRAN Parameters

When creating strings in FORTRAN that are to be passed as parameters, the strings must be terminated by with a null character, CHAR(0) .

Return Values

Upon successful completion:

• A value of 0 is returned.
• The lpid field in the g32_api structure is set to the session ID.

Upon unsuccessful completion:

• A value of -1 is returned.
• 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 fragment illustrates the use of the g32_open function in an api_3270 mode program in C language:

#include <g32_api.h>
main()
{
   struct g32_api *as, asx;  /* asx is statically
                declared*/
   int flag=0;
   int ret;
   as = &asx;      /* as points to an
               allocated structure */
   ret=g32_open(as,flag,"mike","mypassword","a");
   .
   .
   .
}

The following example fragment illustrates the use of the g32_open function in an api_3270 mode program in Pascal language:

program apitest (input, output);
const
%include /usr/include/g32const.inc
type
%include /usr/include/g32types.inc
var
   as : g32_api;
   rc : integer;
   flag : integer;
   sn : stringptr;
   ret : integer;
   uid, pw : stringptr;
%include /usr/include/g32hfile.inc
begin
   flag := 0;
   new(uid,20);
   uid@ := chr(0);
   new (pw,20);
   pw@ := chr(0);
   new (sn,1);
   sn@ := 'a';
   ret := g32open(as,flag,uid,pw,sn);
   .
   .
   .
end.

The following example fragment illustrates the use of the g32_open function in an api_3270 mode program in FORTRAN language:

INTEGER G32OPEN
INTEGER RC, AS(9), FLAG
CHARACTER*20 UID
CHARACTER*10 PW
CHARACTER*2 SN
EXTERNAL G32OPEN
UID = CHAR(0)
PW = CHAR(0)
SN = 'a'//CHAR(0)
FLAG = 0
RC = G32OPEN(AS, FLAG, UID, PW, SN)
   .
   .
   .

Implementation Specifics

The g32_open function is part of the Host Connection Program (HCON).

The g32_open function requires one or more adapters used to connect to a host.

CICS/VS and VSE/ESA do not support API/API or API/API_T modes.

Files