gtpc2mbjC/C++ Language Support User's Guide

TO2_createEnv-Create an Environment Block

This function is called to create a temporary context block called the environment block. It is used to contain information about the user and the data store (DS) and to return error information. The environment block is required on every call to the database.

The TO2_createEnv function will fill in the fields in the environment block that will be needed by TPFCS to satisfy any request.

Format

#include <c$to2.h>
long TO2_createEnv (      TO2_ENV_PTR  *env_ptr,
                          long         *userTokenPtr,
                    const char         *applID,
                    const char         *dsName);

env_ptr
The pointer to a long integer, which is updated to contain a pointer to the created environment. This pointer must be defined as type TO2_ENV_PTR.

userTokenPtr
Reserved for future IBM use. This must point to a word that contains zeros.

applID
The pointer to a 32-character field containing the application name in EBCDIC, left-justified and padded with blanks.

dsName
The pointer to an 8-character field containing the data store name in EBCDIC, left-justified and padded with blanks.

Normal Return

The normal return is a positive value.

Error Return

An error return is indicated by a zero. When zero is returned, use the TO2_getErrorCode function to determine the specific error code. For more information, see Error Handling.

The following error codes are common for this function:

TO2_ERROR_DBID

TO2_ERROR_NOT_INIT

TO2_ERROR_USERTKN

Programming Considerations

Examples

The following example creates a TPFCS environment to allow access to the named data store.

#include <c$to2.h>              /* TO2 API function prototypes        */
#include <stdio.h>              /* APIs for standard I/O functions    */
 
TO2_ENV_PTR    env_ptr;         /* TO2 environment pointer            */
TO2_USER_TOKEN userToken = 0;   /* User token not used                */
 
char applID[32] = "Test.Application.ID             ";
char dsname[8]  = "TEST.DB ";
 
TO2_ERR_CODE     err_code;      /* TO2 error code value               */
TO2_ERR_TEXT_PTR err_text_ptr;  /* TO2 error code text pointer        */

  ·
  ·
  ·
if (TO2_createEnv(&env_ptr, &userToken, applID, dsname) == TO2_ERROR) { printf("createEnv failed!\n"); if (env_ptr ! = NULL) process_error(env_ptr); } else printf("TO2_createEnv is successful!\n");
  ·
  ·
  ·
TO2_deleteEnv (env_ptr);

Related Information

TO2_deleteEnv-Delete an Environment Block.