Overview of User Exit Messages

Edit online

IBM® Connect:Direct® sends and receives messages, using the send_exit_msg() and the recv_exit_msg() functions for a C++ program or the send_exit_msg_c() and the recv_exit_msg_c() functions for a C program. For the exact definition of the data sent in each message, see the files located in d_dir/ndm/include/user_exit.h and d_dir/ndm/include/user_exit2.h.

Note: The copy control block is defined in user_exit2.h.

Statistics Exit Message

Edit online

The statistics exit has only one type of message, the STATISTICS_LOG_MSG.

IBM Connect:Direct sends a STATISTICS_LOG_MSG to the user exit program. Every time IBM Connect:Direct writes a statistic record, this message provides an exact copy of the character string. The STATISTICS_LOG_MSG contains the IBM Connect:Direct statistics record.

File Open Exit Messages

Edit online

The file open exit has four types of messages:

  • FILE_OPEN_OUTPUT_MSG
  • FILE_OPEN_OUTPUT_REPLY_MSG
  • FILE_OPEN_INPUT_MSG
  • FILE_OPEN_INPUT_REPLY_MSG

The file open exit has the following limitations:

  • The oflag parameter passed to the user exit is already calculated based on the file disposition, as explicitly specified on the copy statement or using the default value. If the user exit changes the oflag to truncate and the original disposition is mod meaning the copy will append to the end of file if the file already exists, then the user exit causes the Process to behave differently from how the Process language is documented.
  • If the oflag specifies opening a file with write access and the user exit changes access to read-only, IBM Connect:Direct will fail when it attempts to write to a read-only file.
  • The upload and download parameters that restrict directory access are not enforced by Connect:Direct for UNIX when a file open exit is in use. These restrictions are passed into the file open exit and any enforcement action is the responsibility of the file open exit coder.

FILE_OPEN_OUTPUT_MSG

During the copy statement process, IBM Connect:Direct sends a FILE_OPEN_OUTPUT_MSG to the user exit program to open the destination file. The FILE_OPEN_OUTPUT_MSG contains:

  • The open function oflag parameter (for example, O_CREAT|O_RDWR|O_TRUNC)
  • The open function mode parameter, which controls file permissions
  • UNIX user ID that will own the file
  • UNIX group ID that will own the file
  • UNIX user name
  • A copy of the IBM Connect:Direct copy control block
  • A copy of the IBM Connect:Direct parsed sysopts structure (the copy control block contains the actual raw version from the process)

FILE_OPEN_OUTPUT_REPLY_MSG

The user exit program sends a reply message to the IBM Connect:Direct FILE_OPEN_OUTPUT_MSG. The FILE_OPEN_OUTPUT_REPLY_MSG contains:

  • Status value of zero for successful or non zero for failure
  • Status text message (if status value is failure, status text message is included in the error message)
  • Pipe pid (for pipe I/O, the UNIX process ID of the shell process that is performing the shell command for pipe I/O)
  • Actual file name opened (to be used in statistics log messages)

If the status value is zero for successful, the user exit program must immediately call send_exit_file() or send_exit_file_c() to send the file descriptor of the opened file to IBM Connect:Direct.

FILE_OPEN_INPUT_MSG

During the copy statement Process, IBM Connect:Direct sends a FILE_OPEN_INPUT_MSG to the user exit program to open the source file. The FILE_OPEN_INPUT_MSG contains:

  • The open function oflag parameter (for example, O_RDONLY)
  • The open function mode parameter, which controls file permissions
  • UNIX user ID that will own the file
  • UNIX group ID that will own the file
  • UNIX user name
  • A copy of the IBM Connect:Direct copy control block
  • A copy of the IBM Connect:Direct parsed sysopts structure (the copy control block contains the actual raw version from the Process)

FILE_OPEN_INPUT_REPLY_MSG

This message type is used when the user exit program sends a reply message to the IBM Connect:Direct FILE_OPEN_INPUT_MSG. The FILE_OPEN_INPUT_REPLY_MSG contains:

  • Status value of zero for success or non zero for failure
  • Status text message (if status value is failure, status text message is included in the error message)
  • Pipe pid (for pipe I/O, the UNIX process ID of the shell process that is performing the shell command for pipe I/O)
  • Actual file name opened (used in statistics log messages)

Security Exit Messages

Edit online

The security exit contains four types of messages:

  • GENERATE_MSG
  • GENERATE_REPLY_MSG
  • VALIDATE_MSG
  • VALIDATE_REPLY_MSG
CAUTION:
If the security exit is used, IBM Connect:Direct relies on it for user ID authentication. If the security exit is not implemented correctly, security can be compromised.

GENERATE_MSG

IBM Connect:Direct sends a generate message to the user exit program at the start of a session to establish a security environment. The PNODE sends the GENERATE_MSG to the security exit to determine a user ID and security token to use for authentication on the SNODE. The GENERATE_MSG contains:

  • Submitter ID
  • PNODE ID
  • PNODE ID password, if user specified one
  • SNODE ID
  • SNODE ID password, if user specified one
  • PNODE name
  • SNODE name

GENERATE_REPLY_MSG

The user exit program sends a reply message to IBM Connect:Direct. The GENERATE_REPLY_MSG contains:

  • Status value of zero for success or non zero for failure
  • Status text message (if status value is failure, status text message is included in the error message)
  • ID to use for security context on the SNODE side (may or may not be the same ID as in the generate message)
  • Security token used in conjunction with ID for security context on the SNODE side

VALIDATE_MSG

IBM Connect:Direct sends a validate message to the user exit program. The SNODE sends the VALIDATE_MSG to the security exit to validate the user ID and security token received from the PNODE. The VALIDATE_MSG contains:

  • Submitter ID
  • PNODE ID
  • PNODE ID password, if user specified one
  • SNODE ID
  • SNODE ID password, if user specified one
  • PNODE name
  • SNODE name
  • ID to use with security token
  • Security token (password, PASSTICKET, or other security token)

VALIDATE_REPLY_MSG

The user exit program sends a reply message to the IBM Connect:Direct VALIDATE_MSG. The VALIDATE_REPLY_MSG contains:

  • Status value of zero for success or non zero for failure
  • Status text message (if status value is failure, status text message is included in the error message)
  • ID used for security context
  • Security token to use in conjunction with ID for security context

User Exit Stop Message

Edit online

IBM Connect:Direct sends the stop message, STOP_MSG, when all useful work for the user exit is complete and to notify the user exit to terminate. A user exit should terminate only when a stop message is received or if one of the above listed user exit functions returns an error code.

Copy Control Block

Edit online

The copy control block structure contains the fields, which control how IBM Connect:Direct Processes the copy statement Process file.