tpinit - Initializing the client

Syntax in C

C:      #include <xatmi.h>
       int tpinit (TPCLTINFO *tpinfo)           (in)

Syntax in COBOL

COBOL: 01      TPINIT-REC.
               COPY TPCLTDEF.
       01      TPSTATUS-REC.
               COPY TPSTATUS.
       CALL "TPINIT" USING TPINIT-REC TPSTATUS-REC.

Description

The tpinit function initializes a client and identifies the client to the carrier system. It must be the first XATMI function called in a client program.

In C, you must pass a pointer to the predefined structure TPCLTINFO as a parameter.

The COBOL call needs two parameters:

• First parameter: TPCLTDEF record.

• The second parameter returns the return state of the call.

C structure TPCLTINFO

#define  MAXTIDENT  9
#define  MAXPASSWORD  17
typedef struct {
    long  flags;                    /* for future use */
    char  usrname[MAXTIDENT];
    char  cltname[MAXTIDENT];
    char  passwd [MAXPASSWORD];
} TPCLTINFO;

COBOL record TPCLTDEF

05 FLAG           PIC S9(9) COMP-5.
05 USRNAME        PIC X(8).
05 CLTNAME        PIC X(8).
05 PASSWD         PIC X(16).

A user ID is entered in usrname and a password in passwd. Both parameters are used to establish a conversation, and serve as proof of access authorization on the UTM side. cltname (= local client name) identifies the client to the carrier system.

cltname is

• For Unix, Linux and Windows systems: With UPIC-L it is the PTERM name or the local application name from the upicfile.

• With UPIC-R it is the the upicfile entry or the BCMAP entry (BS2000 systems, see section “Configuration using BCMAP entries (BS2000 systems)”).

If usrname and passwd are initialized with the null string (COBOL: spaces), the security functions are not activated, i.e. there is no access control in openUTM. If at least one of these two parameters contains a valid value, this is checked by UTM.
If cltname is initialized with the null string or with spaces, the local client name is preset to 8 spaces.

In C, if tpinit is called with a null pointer, then no access control is activated and the local client name is preset to 8 blanks. In COBOL, the structure must be filled with spaces for this purpose.

The entries in usrname, passwd, and cltname (if any) must comply with the UTM name conventions, i.e. they can be up to eight (or 16 for passwd) characters in length, wherein the following applies:

• In C, they must be terminated with the end-of-string character (“\0”).

• In COBOL, they must be filled up to the respective length if necessary.

Return codes

In the event of an error, tpinit returns in C the value -1 and sets the tperrno error variable to one of the following values:

TPEINVAL

One or more parameters were assigned invalid values.

TPENOENT

Initialization could not be performed, e.g. there may not be sufficient memory for internal buffers.

TPEPROTO

tpinit was called at an inappropriate time, e.g. the client is already initialized.

TPESYSTEM

An internal error has occurred.

In COBOL, in case of error in the TPINIT call the corresponding tperrno value is supplied directly as the return status.