Programming Guide

Attaches a client to the middleware

client_init [connectionOpt]... [authLevel2] [authLevel3] 
	[NOTIFICATION notifyMethod]

connectionOpt

One or more options that supply information about the client:

CLIENT clientName

Specifies the name of the client, where clientName can be up to 30 characters long. If omitted, the default is an empty string.

USER userName

Specifies a user account (login) name, where userName can be up to 30 characters long. If omitted, the default is an empty string.

GROUP groupName

(Oracle Tuxedo only) Specifies the name of a group associated with this client, where groupName can be up to 15 characters long. If omitted, the default is an empty string.

You can set groupName to associate the client with a resource manager group that is defined in the configuration file. This allows the client to access an XA-compliant resource manager as part of a global transaction.

authLevel2

Supply the application password for client access with this syntax:

PASSWORD password

password specifies the application password, a string of up to 30 characters; however, only the first 8 characters are significant. If omitted, the default is an empty string. You set the application password through the JetNet manager; refer to "Application Password" in JetNet/Oracle Tuxedo Guide for more information.

authLevel3

(Oracle Tuxedo only) Supply level-3 authentication data with one of these syntax clauses:

DATA password

Specifies the user-specific password required by the authentication service.

DATAFUNC dataFunc [POSTFUNC postFunc]

Specifies a function that provides level-3 authentication data and, optionally, a post-connection function that handles successful or failed connections. For the DATAFUNC function's prototype and description, refer to "Authentication Data Function"; for the POSTFUNC function, "Post-Connection Function."

Both functions must be installed. For information on installing a DATAFUNC function, refer to "Client Authentication Functions" in Application Development Guide; for POSTFUNC functions, refer to "Client Post-Connection Functions" in Application Development Guide.

NOTIFICATION notifyMethod

For use by administrator clients only: Specify how the client is notified of unsolicited messages, where notifyMethod has one of these values:

• POLL—Notify by polling for messages. The default polling interval is 10 seconds. To change the interval, set the tp_unsol_poll_interval property. If you are using Panther, this is the default. For Oracle Tuxedo applications, the default can be set in the tuxconfig.

• SIGNAL—Notify by signal. If this option is not available on a given platform, Panther uses POLL instead.

• IGNORE— All unsolicited messages are ignored.

  For example, the following code opens a client connection and specifies to ignore all unsolicited messages:

  client_init CLIENT "shipping" USER user NOTIFICATION IGNORE

  This code specifies that the client be notified of unsolicited messages by polling:

  client_init CLIENT last_name USER "Customer" \
  	NOTIFICATION POLL

JetNet, Oracle Tuxedo

Client

The client_init command opens a client connection to the application middleware–either JetNet or Oracle Tuxedo. Only one connection between client and middleware is allowed. Panther connects a workstation client to the middleware through its settings in configuration variables SMRBHOST and SMRBPORT, which specify the network addresses of one or more server machines; native clients use the settings in the configuration file specified by SMRBCONFIG.

client_init offers several ways to authorize client access to an application. Level-2 authentication provides a single application-wide password; the PASSWORD option is required; the USER and CLIENT options are for informational purposes only and are not validated.

For example, this statement opens a client connection and specifies an application password:

client_init PASSWORD appPassword

Level-3 authentication, available with Oracle Tuxedo, offers user-specific validation as an additional layer of security. Level-3 authentication uses a Oracle Tuxedo service that validates the user name, client name, and user password, as supplied by the USER, CLIENT, and DATA options, respectively. The Oracle Tuxedo service can be configured to validate different combinations of this data.

For example, this command assumes validation at the application and user levels:

client_init USER username PASSWORD appPassword 													DATA userPassword

For more information about setting user-level security in Oracle Tuxedo applications, refer to "Security Administration" in the Oracle Tuxedo Administrator's Guide.

Use the DATAFUNC option if the user password data is more complex than a simple string. On return, the DATAFUNC-specified C function supplies all data that is required by the authentication service, including user name, client name, and group name. For example, the following code opens a client connection for a named client, specifying a function that produces the authentication data:

client_init CLIENT "shipping" DATAFUNC "ship_authorize"

All DATAFUNC functions must be installed; for more information, refer to "Client Authentication Functions" in Application Development Guide.

A DATAFUNC function must conform to this prototype:

long DATAFUNC (VOIDPTR *data,
				 const char *usrname, const char *cltname,
				 const char *passwd, cons char *grpname);

data

Must be set by the DATAFUNC function to the address of the user data. This address must remain valid on return from the function.

srname, cltname, passwd, grpname

Contain the values specified by the corresponding USER, CLIENT, PASSWORD, and GROUP options; otherwise NULL. These values must not be changed by the DATAFUNC function.

When successful, the DATAFUNC function returns the length of the data; a negative value indicates that an error occurred. If the function is successful, the output value of data should be the address of the user data. If dataFunc returns a negative value, or if the address in data is NULL when a positive value is returned, client_init raises a TP_DATAFUNC_FAILED exception of severity TP_COMMAND.

Use the POSTFUNC option to pair a post-connection function with the DATAFUNC function. This C function is always called whether or not the connection is successful.

Panther installs a built-in postFunc sm_tp_free, which deallocates any memory allocated by the dataFunc.

All POSTFUNC functions must be installed; for more information, refer to "Client Post-Connection Functions" in Application Development Guide.

A POSTFUNC function must conform to this prototype:

void POSTFUNC (VOIDPTR data, long datalen,
				 const char *usrname, const char *cltname,
				 const char *passwd, const char *grpname);

data

Contains the address of the user data as set by the DATAFUNC function.

datalen

Contains the length returned by the DATAFUNC function.

usrname, cltname, passwd, grpname

Contain the values specified by the corresponding USER, CLIENT, PASSWORD, and GROUP options; otherwise NULL. These values must not be changed by the POSTFUNC function.

client_init can raise the following exceptions:

Exception	Severity	Cause
TP_CONNECTION_LIMIT	TP_COMMAND	A second connection to the middleware is attempted.
TP_CONNECTION_OPEN_FAILED	TP_ERROR	Connection to the middleware cannot be initiated.
TP_DATAFUNC_FAILED	TP_COMMAND	DATAFUNC function returned a negative value, or address in data is NULL when positive value is returned.
TP_HANDLER_MISSING	TP_ERROR	DATAFUNC and/or POSTFUNC options are specified but do not exist in the appropriate Panther function list.
TP_INVALID_SERVER_COMMAND	TP_COMMAND	Server attempts to use this command.
TP_MONITOR_ERROR	TP_ERROR	Operating system error is detected.
TP_NO_SIGNALS	TP_INFORMATION	Client is not capable of signal-based notification.
TP_PERMISSION_DENIED	TP_ERROR	The middleware does not accept connection.
TP_XA_OPEN_FAILED	TP_ERROR	Unable to open XA-connection resource managers.

client_exit

---

---