Attaches to a session and provides extended open capabilities. If the session does not exist, the session is started.
HCON Library
C (libg3270.a)
Pascal (libg3270p.a)
FORTRAN (libg3270f.a)
#include <g32_api.h>
g32_openx (as, flag, uid, pw, sessionname, timeout)
struct g32_api *as;
int flag;
char * uid;
char * pw;
char * sessionname;
char * timeout;
function g32openx(var as : g32_api; flag: integer;
uid : stringptr;
pw : stringptr;
sessionname : stringptr;
timeout : stringptr) : integer; external;
INTEGER G32OPENX,RC,AS(9),FLAG
EXTERNAL G32OPENX
CHARACTER* XX UID, PW, SESSIONNAME
RC = G32OPENX (AS, FLAG, UID, PW, SESSIONNAME, TIMEOUT)
The g32_openx function attaches to a session. If the session does not exist, the session is started. This is an automatic login. The user is logged in to the host if requested. The g32_openx function provides additional capability beyond that of the g32_open function. An application program must call g32_openx or g32_open before any other API function.
If an API application is run automatically, the function performs an automatic login.
The g32_openx 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. Applications programs using the FORTRAN language for the HCON API must include and link both the C and FORTRAN libraries.
The g32_openx function allows for a varying number of parameters after the flag parameter. The as and flag parameters are required; the uid, pw, session, and timeout parameters are optional.
With the g32_open function, the timeout parameter does not exist and the parameters for uid, pw, and session are not optional. The reason for making the last four parameters optional is that the system either prompts for the needed information (uid and pw) or defaults with valid information (session or timeout).
Unless all of the parameters are defined for this function, the parameter list in the calling statement must be terminated with the integer 0 (like the exec function). Providing an integer of 1 forces a default on a parameter. Use the default to provide a placeholder for optional parameters that you do not need to supply.
as | Specifies a pointer to the g32_api structure. |
flag | Requires one of the following:
|
uid | Specifies a pointer to the login ID string. 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 the latter case the user is prompted only for a password. The login ID is a string consisting of the host user ID and an optional list of additional variables separated by commas, as shown in the example:
userid,var1,var2,... |
In this example, var1 is the login script name (when using AUTOLOG) and var2 is the optional trace and time values. The list is passed to the automatic procedure. | |
pw | Specifies a pointer to the password string associated with the login ID string. The following usage considerations apply to the pw parameter: |
sessionname | Points 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. Parameters for each session are specified in a per session profile. |
timeout | Specifies a pointer to a numerical string that specifies the amount of nonactive time in seconds allowed to occur between the workstation and the host operations (that is, g32_read and G32WRITE). This parameter is optional. If no value is provided in the calling statement, the default value is 15. The minimum value allowed is 1. There is no maximum value limitation. |
When using C as a programming language, you can make use of the feature of variable numbered parameters. In Pascal, however, this feature is not allowed. Therefore, calls to the g32_openx function must contain all six parameters.
To use defaults for the four optional parameters of C, provide a variable whose value is a null string.
Note: The use of the integer 1 is not allowed in the Pascal version of the g32_openx function. Space must be allocated for any string pointers prior to calling the g32_openx function.
as | Specifies the g32_api structure. |
flag | Signals whether the login procedure should be performed:
|
uid | Specifies a pointer to the login ID string. 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 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. The following usage considerations apply to the pw parameter: |
sessionname | Points 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. Parameters for each session are specified in a per session profile. |
timeout | Specifies a pointer to a numerical string that specifies the amount of nonactive time in seconds allowed to occur between the workstation and the host operations (that is, g32_read and g32WRITE). This parameter is optional. If no value is provided in the calling statement, the default value is 15. The minimum value allowed is 1. There is no maximum value limitation. |
FORTRAN calls to G32_OPENX must contain all six parameters. To use defaults for the four optional parameters of C language, provide a variable whose value is a null string. Note that the use of the integer 1 is not allowed in the FORTRAN version of this function. When creating strings in FORTRAN that are to pass as parameters, the strings must be linked with a null character, CHAR(0) .
AS | Specifies the g32_api equivalent structure as an array of integers. |
FLAG | Signals that the login procedure should be performed:
|
UID | Specifies a pointer to the login ID string. 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 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. The following usage considerations apply to the pw parameter: |
SESSIONNAME | Specifies 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. Parameters for each session are specified in a per session profile. |
TIMEOUT | Specifies a numerical string that specifies the amount of nonactive time in seconds allowed to occur between the workstation and the host operations (that is, g32_read/g32WRITE). There is no maximum to this, but the minimum is 1. |
0 | Indicates successful completion. The lpid field in the g32_api structure is set to the session ID. |
-1 | Indicates an error has occurred. |
g32_openx (AS, 0, "john, tso, trace", "j12hn");
g32_openx (AS, 1, "john", "j12hn", "Z", 0);
g32_openx (AS, 1, 0); OR g32_openx (AS, 0, 0);
g32_openx (AS, 0, UID, Pw, Sessionname, TimeOut);
g32_openx (AS, 1, UID, Pw, 0);
g32_openx (AS, 0, 1, 1, 1, "60");
g32_openx (AS, 0, 1, 1, Session, 0);
#include <g32_api.h> main() { struct g32_api *as, asx; /* asx is a temporary struct */ /* g32.api so that storage */ /* is allocated */ int flag=0; int ret; sn = &nm; as = &asx; /* as points to an allocated structure */ ret=g32_openx(as,flag,"mike","mypassword","a","60"); . . . }
Note: Only the first two parameters are mandatory. The remaining parameters can be terminated with a 0 . For example:ret = g32_openx(as.flag,0);Null characters may be substituted for any of the string values if profile or command values are desired.
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; timeout : 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'; new (timeout,32); timeout@ := '60'; ret := g32openx(as,flag,uid,pw,sn,timeout); . . . end.
INTEGER G32OPENX INTEGER RC, AS(9), FLAG CHARACTER*20 UID CHARACTER*10 PW CHARACTER*10 TIMEOUT CHARACTER*1 SN EXTERNAL G32OPENX UID = CHAR(0) TIMEOUT = CHAR(0) MODEL = CHAR(0) PW = CHAR(0) SN = 'a'//CHAR(0) TIMEOUT = '60'//CHAR(0) FLAG = 0 RC = G32OPENX(AS, FLAG, UID, PW, SN, TIMEOUT) . . .
The g32_openx function is part of the Host Connection Program (HCON).
The g32_openx 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.
/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. |
List of HCON Programming References in 3270 Host Connection Program 2.1 and 1.3.3 for AIX: Guide and Reference.
Programming HCON Overview in 3270 Host Connection Program 2.1 and 1.3.3 for AIX: Guide and Reference.