g32_openx Function

Purpose

Attaches to a session and provides extended open capabilities. 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_openx (as, flag, uid, pw, sessionname, timeout)

struct g32_api * as;

int   flag;

char * uid;

char * pw;

char *  sessionname;

char * timeout;

Pascal Syntax

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

  uid : stringptr;

  pw : stringptr;

  sessionname : stringptr;

  timeout : stringptr) : integer; external;

FORTRAN Syntax

INTEGER G32OPENX,RC, AS(9), FLAG

EXTERNAL G32OPENX

CHARACTER* XX  UID,  PW,  SESSIONNAME

RC = G32OPENX (AS, FLAG, UID, PW, SESSIONNAME,  TIMEOUT)

Description

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

C Parameters

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.

Parameter Description
as Specifies a pointer to the g32_api structure.
flag Requires one of the following:
  • Set the flag parameter to 0, if the emulator is running and the user is logged on to host.
  • Set the flag parameter to 1 if the emulator is running, the user is not logged on to host, and the API application is to perform the login/logoff procedure.

    The g32_openx function ignores the flag parameter, if the emulator is not running and the API application executes an automatic login/logoff procedure.

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:
  • If no password is to be specified, the user can specify a null string.
  • If no value is provided and the program is running automatically, the login procedure prompts the user for the password.
  • If the uid parameter is a null string, the pw parameter is ignored.
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.

Pascal Parameters

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.
Parameter Description
as Specifies the g32_api structure.
flag Signals whether the login procedure should be performed:
  • Set the flag parameter to 0. If the emulator is running, the user is logged on to host.
  • Set the flag parameter to 1. If the emulator is running, the user is not logged on to host, and the API application performs the login/logoff procedure.
  • If the emulator is not running and the API application executes an automatic login/logoff procedure, the value of flag is ignored.
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:
  • If no password is to be specified, the user can specify a null string.
  • If no value is provided and the program is running automatically, the login procedure prompts the user for the password.
  • If the uid parameter is a null string, the pw parameter is ignored.
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 Parameters

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

Parameter Description
AS Specifies the g32_api equivalent structure as an array of integers.
FLAG Signals that the login procedure should be performed:
  • Set the FLAG parameter to 0, if the emulator is running, the user is logged on to host.
  • Set the FLAG parameter to 1, if the emulator is running, the user is not logged on to host.
  • 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 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:
  • If no password is to be specified, the user can specify a null string.
  • If no value is provided and the program is running automatically, the login procedure prompts the user for the password.
  • If the uid parameter is a null string, the pw parameter is ignored.
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.

Return Values

Item Description
0 Indicates successful completion. The lpid field in the g32_api structure is set to the session ID.
-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

  1. To use the g32_openx function with fewer than four optional string constant parameters specified and with AUTOLOG, enter:
    g32_openx (AS, 0, "john, tso, trace", "j12hn");
  2. To use the g32_openx function with fewer than four optional string constant parameters specified and with the automatic login facility, enter:
    g32_openx (AS, 1, "john", "j12hn", "Z", 0);
  3. To use the g32_openx function with all optional parameters not specified, enter:
    g32_openx (AS, 1, 0);
    
    OR
    
    g32_openx (AS, 0, 0);
  4. To use the g32_openx function with four variable optional parameters, enter:
    g32_openx (AS, 0, UID, Pw, Sessionname, TimeOut);
  5. To use the g32_openx function with fewer than four variable optional parameters, enter:
    g32_openx (AS, 1, UID, Pw, 0);
  6. To use the g32_openx function with two default optional parameters, enter:
    g32_openx (AS, 0, 1, 1, 1, "60");
  7. To use the g32_openx function with a mixture:
    g32_openx (AS, 0, 1, 1, Session, 0);
  8. To use the g32_openx function within a program segment in the C language:
    #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.
  9. To use the g32_openx function within a program segment in the 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;
       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.
  10. To use the g32_openx function within a program segment in the FORTRAN language:
    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)
       .
       .
       .