User Exit Functions

A connection between the user exit and IBM® Connect:Direct® is established when the user exit program calls the exit_child_init() or exit_child_init_c() function. The connection is terminated through a specially designated stop message. The types of messages are defined in the include file user_exit.h. The following functions facilitate communications between the user exit and IBM Connect:Direct:

C++ Function C Function Description
exit_child_init() exit_child_init_c() Use this function as the first line in a user exit program to initialize communications between IBM Connect:Direct and the user exit program.
recv_exit_msg() recv_exit_msg_c() Used by both IBM Connect:Direct and the user exit program to receive a message from the other Process. The receive exit messages wait for a response from the other Process.
send_exit_file() send_exit_file_c() The user exit program uses this function when it has opened a file for IBM Connect:Direct. This function uses underlying UNIX methods to pass an open file descriptor. from one Process to another.
send_exit_msg() send_exit_msg_c() Both IBM Connect:Direct and the user exit program use this function to send a message to the other Process. Send messages are followed with a receive message to get the response from the other Process.

Initializing Communications with exit_child_init() or exit_child_init_c()

Use the exit_child_init() or exit_child_init_c() function as the first line of code of the user exit program to initialize communications. This function performs a check to verify that each side is ready to communicate. Following is the format of the exit_child_init() function:

int exit_child_init( char * logfile )

The exit_child_init() or exit_child_init_c() function has the following parameter:

Parameter Description Value
logfile The name of the log or trace file that is opened for use by the user exit programs. Because the file open and security exit are started by SMGR, which is running as root, the exits also run as root. Running the exits as root can cause problems with file permissions of the log file, so logfile enables you to easily change owner or permissions on the file. See the sample exit in d_dir/ndm/src/exit_skeleton.c for more details. Name of log file or trace file

The exit_child_init() or exit_child_init_c() function have the following return codes. Return codes for the function are defined in ndmapi.h.

Return Code Description
GOOD_RC

Communications between IBM Connect:Direct and the user exit program were successfully initialized.

ERROR_RC

Communications between IBM Connect:Direct and the user exit program could not be initialized.

Waiting for a Message Using recv_exit_msg() or recv_exit_msg_c()

The recv_exit_msg() or recv_exit_msg_c() function waits until it receives a message from IBM Connect:Direct. Control is suspended until a message is received or an error occurs. The recv_exit_msg() has the following format:

int recv_exit_msg( int exit_flag )
	int * msg_type, 
	char * recv_buf, 
	int * recv_buf_len

The recv_exit_msg() or recv_exit_msg_c() functions have the following parameters:

Parameter Description Value
exit_flag A flag to specify the recipient ID. The only valid value a user exit program can use is EXIT_PROGRAM. EXIT_PROGRAM
msg_type A pointer to the name of the received message. Messages are requests from IBM Connect:Direct and the associated response from the user exit program. Pointer to message
recv_buf A pointer to the memory location of the message. Pointer to message
recv_buf_len The length in bytes of the message to be received. Length of message

The recv_exit_msg()or recv_exit_msg_c() functions have the following return codes. Return codes for the function are defined in ndmapi.h.

Return Code Description
GOOD_RC

The message was received successfully.

ERROR_RC

An error occurred and the message was not received successfully. Possible causes include: IBM Connect:Direct terminated, an invalid value used for the exit_flag parameter, or the receiving buffer not large enough to hold the message received.

Passing a File Descriptor Using send_exit_file() or send_exit_file_c()

Use the send_exit_file() or send_exit_file_c() function to pass a file descriptor from one Process to another Process. Following is the format of send_exit_file():

int send_exit_file int  exit_flag
	int fd

Following are the parameters for send_exit_file() or send_exit_file_c():

Parameter Description Value
exit_flag A flag to specify the sender ID. The only valid value a user exit program can use is EXIT_PROGRAM. EXIT_PROGRAM
fd The file descriptor of a file that the user exit program opened in the place of IBM Connect:Direct, similar to one returned by the open(2) function. File descriptor

The send_exit_file() or send_exit_file_c() function calls have the following return codes. Return codes for the function are defined in ndmapi.h.

Header Header
GOOD_RC

The file descriptor was received successfully.

ERROR_RC

An error occurred and the file descriptor was not sent successfully. Possible causes include: IBM Connect:Direct terminated, an invalid value used for the exit_flag or fd parameters, or the last message sent was not send_exit_msg.

Sending a Message to IBM Connect:Direct Using send_exit_msg() or send_exit_msg_c()

The send_exit_msg() or send_exit_msgc() function enables the user exit program to send a message to IBM Connect:Direct. This function returns control to the caller immediately after the message is queued.

Following is the format of the send_exit_msg() function:

int send_exit_msg int exit_flag
	int msg_type,
	char * send_buf,
	int send_buf_len

Following are the parameters for send_exit_msg() or send_exit_msg_c():

Parameter Description Value
exit_flag A flag to specify the sender ID. The only valid value a user exit program can use is EXIT_PROGRAM. EXIT_PROGRAM
msg_type A message name. Messages are requests from IBM Connect:Direct and the associated response from the user exit program. Pointer to message
send_buf A pointer to the memory location of the message to be sent. Pointer to message
send_buf_len The length in bytes of the message to be sent. Length of message

Following are the return codes for send_exit_msg() or send_exit_msg_c(). Return codes for the function are defined in ndmapi.h.

Return Code Description
GOOD_RC

The message was sent successfully.

ERROR_RC

An error occurred and the message was not sent successfully. Possible causes include: IBM Connect:Direct terminated or an invalid value is used for the exit_flag or msg_type parameters.