cwbUN_GetSystemHandle

Purpose

Returns a system handle that contains the security (SSL), userID, and password settings that are used for this iSeries™ system. The system handle will have the settings that were configured in iSeries Navigator for the input iSeries system name.

If the application name is set to NULL, the returned system handle will be unique. If the application name is set, the same system handle that matches the application name will be returned.

If an application requires a unique OS/400^® job for a system, then NULL or a unique name should be passed in for the application name.

If an application requires to share an OS/400 job, then all callers of this function should pass in the same application name.

Syntax

CWBAPI unsigned int WINAPI cwbUN_GetSystemHandle(
    char * szSystemName,
    char * szAppName,
    cwbCO_SysHandle * systemHandle
    );

Parameters

char * szSystemName - input

Pointer to an ASCIIZ string that contains the name of the system for which you want a system handle to be created.

char * szAppName - input

Pointer to an ASCIIZ string of no more than 12 characters. This uniquely identifies the application that will share a single system handle.

cwbCO_SysHandle * systemHandle - output

Pointer to the handle of the system for this system name.

Return Codes

The following list shows common return values:

CWB_OK

Successful completion.

CWBUN_NULL_PARM

System name was NULL.

CWBUN_INVALID_NAME_PARM

The system name is not valid.

CWB_NON_REPRESENTABLE_UNICODE_CHAR

One or more input UNICODE characters have no representation in the code page that is being used.

CWB_API_ERROR

The system handle could not be returned.

Usage

This function must be used by all third-party applications that want to support SSL using the iSeries Access for Windows^® APIs. For example, all iSeries Access for Windows communications APIs require a system handle to support SSL.

When the caller of this function no longer needs the system handle for communications, the handle can be released by calling function cwbUN_ReleaseSystemHandle.

All handles will be released when the iSeries Navigator application (cwbunnav.exe) terminates.