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)

Pascal Syntax

FORTRAN Syntax

EXTERNAL G32OPENX

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.

userid,var1,var2,...

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.

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

Return Values

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