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.

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.

C Parameters

Item	Description
as	Specifies a pointer to the g32_api structure. Status is returned in this structure.
flag	Signals whether the login procedure should be performed. Flag values are as follows: If the emulator is running and the user is logged in to the host, the value of the flag parameter must be 0. If the emulator is running, the user is not logged in to the host, and the API logs in to the host, the value of the flag parameter must be set to 1. If the emulator is not running and the API application executes an automatic login/logoff procedure, the value of the flag parameter is ignored.
uid	Specifies a pointer to the login ID string if the g32_open function logs in to the host. If the login ID is a null string, the login procedure prompts the user for both the login ID and the password unless the host login ID is specified in the session profile in which case the user is prompted only for a password. The login ID is a string consisting of the host user ID and, optionally, a list of comma-separated AUTOLOG variables, which is passed to the implicit procedure. The following is a sample list of AUTOLOG variables: `userid, node_id, trace, time=n,...`
pw	Specifies a pointer to the password string associated with the login ID string. The following usage considerations apply to the pw parameter: If no password is to be specified, the user can specify a null string. If no value is provided and the program is running implicitly, the login procedure prompts the user for the password. If the uid parameter is a null string, the pw parameter is ignored.
sessionname	Specifies a pointer to the name of a session. The session name is a single character in the range of a through z. Capital letters are interpreted as lowercase letters.

Pascal Parameters

Item	Description
as	Specifies the g32_api structure.
flag	Signals whether the login procedure should be performed. If the emulator is running, the user is logged in to the host, and the API application executes as a subshell of the emulator, the value of the flag parameter must be 0. If the emulator is running, the user is not logged in to the host, and the API application executes as a subshell of the emulator and the application is to perform an automatic login/logoff procedure, the value of the flag parameter must be set to 1. If the emulator is not running and the API application executes an automatic login/logoff procedure, the value of the flag parameter is ignored.
uid	Specifies a pointer to the login ID string. If the user ID is a null string, the login procedure prompts the user for both the user ID and the password unless the host login ID is specified in the session profile. In the latter case, the user is prompted only for a password.
pw	Specifies a pointer to the password string associated with the login ID string. If it points to a null string, the login procedure prompts the user for the password. This parameter is ignored if the uid parameter is a null string.
sessionname	Specifies a pointer to the name of a session, which indicates the host connectivity to be used by the API application. The session name is a single character in the range of a through z. Capital letters are interpreted as lowercase letters.

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

Parameter	Description
AS	Specifies the g32_api equivalent structure as an array of integers.
FLAG	Signals whether the login procedure should be performed.
UID	Specifies a pointer to the login ID string. If the user ID is a null string, the login procedure prompts the user for both the user ID and the password unless the host login ID is specified in the session profile. In the latter case, the user is prompted only for a password.
PW	Specifies a pointer to the password string associated with the login ID string. If the parameter specifies a null string, the login procedure prompts the user for the password. This parameter is ignored if the uid parameter is a null string.
SESSIONNAME	Specifies the name of a session, which indicates the host connectivity to be used by the API application. The session name is a single character in the range of a through z. Capital letters are interpreted as lowercase letters.

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