Connect:Direct®

for UNIX

User’s Guide

Version 4.0
Connect:Direct for UNIX User’s Guide
Version 4.0
Second Edition
(c) Copyright 1999-2009 Sterling Commerce, Inc. All rights reserved. Additional copyright information is located in the release notes.
STERLING COMMERCE SOFTWARE
***TRADE SECRET NOTICE***
THE CONNECT:DIRECT SOFTWARE (“STERLING COMMERCE SOFTWARE”) IS THE CONFIDENTIAL AND TRADE SECRET
PROPERTY OF STERLING COMMERCE, INC., ITS AFFILIATED COMPANIES OR ITS OR THEIR LICENSORS, AND IS PROVIDED
UNDER THE TERMS OF A LICENSE AGREEMENT. NO DUPLICATION OR DISCLOSURE WITHOUT PRIOR WRITTEN PERMISSION.
RESTRICTED RIGHTS.
This documentation, the Sterling Commerce Software it describes, and the information and know-how they contain constitute the proprietary,
confidential and valuable trade secret information of Sterling Commerce, Inc., its affiliated companies or its or their licensors, and may not be used
for any unauthorized purpose, or disclosed to others without the prior written permission of the applicable Sterling Commerce entity. This
documentation and the Sterling Commerce Software that it describes have been provided pursuant to a license agreement that contains prohibitions
against and/or restrictions on their copying, modification and use. Duplication, in whole or in part, if and when permitted, shall bear this notice and
the Sterling Commerce, Inc. copyright notice. As and when provided to any governmental entity, government contractor or subcontractor subject
to the FARs, this documentation is provided with RESTRICTED RIGHTS under Title 48 52.227-19. Further, as and when provided to any
governmental entity, government contractor or subcontractor subject to DFARs, this documentation and the Sterling Commerce Software it
describes are provided pursuant to the customary Sterling Commerce license, as described in Title 48 CFR 227-7202 with respect to commercial
software and commercial software documentation.
These terms of use shall be governed by the laws of the State of Ohio, USA, without regard to its conflict of laws provisions. If you are accessing
the Sterling Commerce Software under an executed agreement, then nothing in these terms and conditions supersedes or modifies the executed
agreement.
Where any of the Sterling Commerce Software or Third Party Software is used, duplicated or disclosed by or to the United States government or a
government contractor or subcontractor, it is provided with RESTRICTED RIGHTS as defined in Title 48 CFR 52.227-19 and is subject to the
following: Title 48 CFR 2.101, 52.227-19, 227.7201 through 227.7202-4, FAR 52.227-14, and FAR 52.227-19(c)(1-2) and (6/87), and where
applicable, the customary Sterling Commerce license, as described in Title 48 CFR 227-7202 with respect to commercial software and commercial
software documentation including DFAR 252.227-7013, DFAR 252,227-7014, DFAR 252.227-7015 and DFAR 252.227-7018, all as applicable.
The Sterling Commerce Software and the related documentation are licensed either “AS IS” or with a limited warranty, as described in the Sterling
Commerce license agreement. Other than any limited warranties provided, NO OTHER WARRANTY IS EXPRESSED AND NONE SHALL BE
IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR USE OR FOR A PARTICULAR PURPOSE.
The applicable Sterling Commerce entity reserves the right to revise this publication from time to time and to make changes in the content hereof
without the obligation to notify any person or entity of such revisions or changes.
Connect:Direct is a registered trademark of Sterling Commerce. Connect:Enterprise is a registered trademark of Sterling Commerce, U.S. Patent
Number 5,734,820. All Third Party Software names are trademarks or registered trademarks of their respective companies. All other brand or
product names are trademarks or registered trademarks of their respective companies.

Sterling Commerce, Inc.

4600 Lakehurst Court Dublin, OH 43016-2000 *
614/793-7000

CDUNXUG902
 Contents

Chapter 1 About Connect:Direct for UNIX 7

Server Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Process Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Command Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Session Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
File Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Connect:Direct Secure+ Option for UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Applications Programming Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Command Line Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Sterling Control Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Connect:Direct Browser User Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Connect:Direct Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Local and Remote Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Transmission Control Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Network Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
User Authorization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Process Restart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Archive Statistics Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Sample Processes, Shell Scripts, and API Programs. . . . . . . . . . . . . . . . . . . . . 17
Connect:Direct Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Connect:Direct for UNIX Configuration Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Connect:Direct for UNIX Directory Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Connect:Direct Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Task Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Chapter 2 Controlling and Monitoring Processes 23

Using the Command Line Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Starting the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Using Job Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Using History with the CLI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Stopping the CLI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Connect:Direct for UNIX User’s Guide 3

 Contents

Guidelines for Using Connect:Direct Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Command Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Parameter Abbreviations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Limitations on Using Programs and Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Generic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Submitting a Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Parameters for submit Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Sample submit Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Submitting a Process That Runs Every Week . . . . . . . . . . . . . . . . . . . . . . . 36
Submitting a Process with a Start Time Specified . . . . . . . . . . . . . . . . . . . . 37
Submitting a Process with No File Value . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Submitting a Process and Turning On Tracing. . . . . . . . . . . . . . . . . . . . . . . 37
Changing Process Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Deleting a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Removing a Process from the Execution Queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Stopping Connect:Direct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Viewing a Process in the TCQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Monitoring the Process Status on the TCQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Determining the Outcome of a Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Sample Detailed Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Sample Summary Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Running System Diagnostics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

Chapter 3 Process Queuing 63

About the Transmission Control Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Scheduling Connect:Direct Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Progression of a Process Through the TCQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
About the Execution Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
About the Wait Queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
About the Timer Queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
About the Hold Queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Chapter 4 Using Connect:Direct Utilities 69

Working With Translation Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Creating and Modifying a Translation Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Example—Creating a Translation Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Example—Modifying a Model Translation Table. . . . . . . . . . . . . . . . . . . . . . . . . 72
Using Translation During File Transfer Operations. . . . . . . . . . . . . . . . . . . . . . . 72
Diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Accessing Connect:Direct Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
About the Message File Content. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Understanding the Message File Record Format . . . . . . . . . . . . . . . . . . . . . . . . 74
Displaying Message Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Using License Key File Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

4 Connect:Direct for UNIX User’s Guide

 Contents

Precompressing/Decompressing Files Using the Standalone Batch

Compression Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Special Considerations for Using the Standalone Batch Compression Utility. . . 76
Using the Standalone Batch Compression Utility . . . . . . . . . . . . . . . . . . . . . . . . 77
Example—Precompressing a Text File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Example—Precompressing a Text File With Codepage Conversion . . . . . . . . . 80
Example—Precompressing a Binary File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Example—Decompressing a Text File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Examples—csdacomp Command Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Example—Decompressing the File on the Remote Node During the
Copy Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Example—Sending Precompressed File to z/OS and Storing It as
Precompressed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Validating Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Generating a Configuration Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Reporting on the Base Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Reporting on Connect:Direct Secure+ Option for UNIX . . . . . . . . . . . . . . . . . . . 86
Reporting on Connect:Direct UNIX for SWIFTNet . . . . . . . . . . . . . . . . . . . . . . . 87

Chapter 5 Writing Custom Programs 89

Compiling Custom Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Writing Custom C Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Creating a Connection to Connect:Direct Using ndmapi_connect() or
ndmapi_connect_c() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Terminating a Connection Using ndmapi_disconnect() or
ndmapi_disconnect_c() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Receiving Responses Using ndmapi_recvresp() or ndmapi_recvresp_c() . . . . . 94
Sending a Command to Connect:Direct Using ndmapi_sendcmd() or
ndmapi_sendcmd_c() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Writing Custom C++ Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Chapter 6 Writing User Exits 105

Understanding User Exit Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

User Exit Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Initializing Communications with exit_child_init() or exit_child_init_c() . . . . . . . . 106
Waiting for a Message Using recv_exit_msg() or recv_exit_msg_c() . . . . . . . . . 107
Passing a File Descriptor Using send_exit_file() or send_exit_file_c() . . . . . . . . 108
Send a Message to Connect:Direct Using send_exit_msg() or
send_exit_msg_c() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Understanding User Exit Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Statistics Exit Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
File Open Exit Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
FILE_OPEN_OUTPUT_MSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
FILE_OPEN_OUTPUT_REPLY_MSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
FILE_OPEN_INPUT_MSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
FILE_OPEN_INPUT_REPLY_MSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Security Exit Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
GENERATE_MSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
GENERATE_REPLY_MSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Connect:Direct for UNIX User’s Guide 5

 Contents

VALIDATE_MSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
VALIDATE_REPLY_MSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
User Exit Stop Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Copy Control Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Exit Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Glossary 115

Index 121

6 Connect:Direct for UNIX User’s Guide

 Chapter 1

About Connect:Direct for UNIX

Connect:Direct links technologies and moves all types of information between networked systems
and computers. It manages high-performance transfers by providing such features as automation,
reliability, efficient use of resources, application integration, and ease of use. Connect:Direct offers
choices in communications protocols, hardware platforms, and operating systems. It provides the
flexibility to move information among mainframe systems, midrange systems, desktop systems,
and LAN-based workstations.
Connect:Direct is based on client-server architecture. The Connect:Direct server components
interact with the user interfaces (API, CLI, Connect:Direct Browser User Interface, and Sterling
Control Center) to enable you to submit, execute, and monitor Connect:Direct statements and
commands.

Server Components
Connect:Direct has the following server components:

Process Manager
The Process Manager (PMGR) is the daemon that initializes the Connect:Direct server
environment. The PMGR provides the following functions:
✦ Initializes Connect:Direct
✦ Accepts connection requests from Connect:Direct client APIs and remote nodes
✦ Creates Command Manager and Session Manager child Processes to communicate with APIs
and remote nodes
✦ Accepts requests from Command Managers and Session Managers when centralized
Connect:Direct functions are required
✦ Stops Connect:Direct

Note: Any application, including End User Applications (EUA), can run on any computer as long as it can
connect to the PMGR.

Connect:Direct for UNIX User’s Guide 7

Chapter 1 About Connect:Direct for UNIX

Command Manager
A Command Manager (CMGR) is created for every API connection that is successfully established.
The number of Command Managers that a PMGR can create is system-dependent and limited by
the number of file descriptors available for each UNIX Process. The number of file descriptors set
up by the UNIX operating system may affect Connect:Direct operation. You must define enough
file descriptors to handle the number of concurrent Connect:Direct sessions allowed, which can be
as many as 999.
The CMGR provides the following functions:
✦ Executes commands sent by the API and sends the results back to the API
✦ Carries out the Connect:Direct authentication procedure, in conjunction with the API, to
determine access to Connect:Direct
✦ Interacts with the PMGR when executing commands

Session Manager
The Session Manager (SMGR) is created and invoked by the PMGR when resources are available
and either a Process is ready to run or a remote node requests a connection with a local node. The
SMGR provides the following functions:
✦ Performs the necessary Connect:Direct work
✦ Acts as a primary node (PNODE) and initiates Process execution
✦ Acts as a secondary node (SNODE) to participate in a Process initiated by the PNODE
When an SMGR is created to execute a Process submitted to a node, it creates the connection to the
remote node. If the SMGR is started by the PMGR to execute local Processes, the SMGR runs each
Process on this session until all Processes are completed.
If an SMGR is created because a remote node initiated a connection, the SMGR completes the
connection. If the SMGR is started by the PMGR to execute remote Processes, the SMGR executes
remote Process steps supplied by the remote SMGR until the remote SMGR completes all of its
Processes.
The SMGR depends on the PMGR for Transmission Control Queue (TCQ) services and other
centralized services. Refer to the Transmission Control Queue on page 13 for an overview of the
TCQ.

File Agent
Connect:Direct File Agent is a feature of Connect:Direct, which provides unattended file
management. File Agent monitors watched directories to detect new files. When File Agent detects
a new file, it either submits a default Process or evaluates the file using rules to override the default
Process and to determine which Process to submit. You create rules to submit different Processes
based on the following properties:
✦ Specific or partial file names
✦ File size
✦ System events

8 Connect:Direct for UNIX User’s Guide

 User Interfaces

You create the Processes used by File Agent on Connect:Direct; you cannot create them using File
Agent.
To achieve optimum performance, configure File Agent to communicate with the Connect:Direct
node where it is installed. File Agent can be installed on UNIX, Windows, and z/OS operating
systems. For information to help you plan how to implement File Agent, see the Managing Files
with Connect:Direct File Agent chapter in your Connect:Direct administration guide or getting
started guide. The Connect:Direct File Agent Help contains instructions for configuring File Agent.

Connect:Direct Secure+ Option for UNIX

The Connect:Direct Secure+ Option application provides enhanced security for Connect:Direct and
is available as a separate component. It uses cryptography to secure data during transmission. You
select the security protocol to use with Secure+ Option.
To use Connect:Direct Secure+ Option for communications with remote nodes, you must have node
records in the Secure+ Option parameters file that duplicate the adjacent node records in the
Connect:Direct network map. You can populate the Secure+ Option parameters file from entries
defined in an existing network map. For more information about creating the Connect:Direct
Secure+ Option parameters file and configuring nodes for Secure+ Option, refer to the
Connect:Direct Secure+ Option for UNIX Implementation Guide.

User Interfaces
Connect:Direct has the following user interfaces, which enable you to create, submit, and monitor
Processes.

Applications Programming Interface

The UNIX Applications Programming Interface (API) enables you to write programs that work
with Connect:Direct. Several API functions are provided to allow an End User Application (EUA)
to perform the following tasks:
✦ Establish an API connection to the Connect:Direct server
✦ Terminate an API connection to the Connect:Direct server
✦ Send a command to Connect:Direct
✦ Receive responses from commands

Command Line Interface

The Command Line Interface (CLI) enables you to perform the following tasks:
✦ Issue Connect:Direct commands
✦ Monitor Processes
The default CLI command prompt is direct >. Refer to the Controlling and Monitoring Processes
chapter in the Connect:Direct for UNIX User’s Guide for additional information about the CLI.

Connect:Direct for UNIX User’s Guide 9

Chapter 1 About Connect:Direct for UNIX

Sterling Control Center

Sterling Control Center is a centralized management system that provides operations personnel with
continuous enterprise-wide business activity monitoring capabilities for Connect:Direct for z/OS,
UNIX, Windows, HP NonStop, and i5OS servers; Connect:Direct Select; and Connect:Enterprise
for UNIX and Connect:Enterprise for z/OS servers; and Gentran Integration Suite (GIS). Sterling
Control Center enables you to:
✦ Manage multiple servers
Š Group individual servers into server groups for a single view of system-wide activity
Š View status and statistics on active or completed processing
Š Suspend, release, stop, and delete Connect:Direct Processes on z/OS, UNIX, Windows,
Select, and HP NonStop platforms
Š Stop Connect:Direct servers on z/OS, Windows, HP NonStop,i5OS, and UNIX platforms.
✦ Monitor service levels
Š View active and completed processes across the servers within your network

Š Receive notification of data delivery events that occur or do not occur as scheduled
Š Define rules that, based on processing criteria, can generate an alert, send an e-mail
notification, generate a Simple Network Management Protocol (SNMP) trap to an
Enterprise Management System (EMS), run a system command, or issue a server
command
Š Monitor for alerts, such as a server failure or a Process not starting on time
Š Create service level criteria (SLCs) that define processing schedules, monitor Processes,
files within Processes, and file transfers for compliance with these schedules, and generate
alerts when the schedules are not met
✦ Analyze key operational metrics
✦ Create customized reports to document and analyze processing activity based on criteria you
define

10 Connect:Direct for UNIX User’s Guide

 User Interfaces

✦ Validate user authenticity for console-to-engine connections using one or more of four
authentication methods, including password validation, host name identification, Windows
domain, and TCP/IP address (or three methods in the case of the Web console, which does not
support domain authentication)
✦ Identify additional Connect:Direct servers that may need to be monitored based on
communications with a currently monitored server
Sterling Control Center enhances operational productivity and improves the quality of service by:
✦ Ensuring that critical processing windows are met
✦ Reducing impact on downstream processing by verifying that expected processing occurs
✦ Providing proactive notification for at-risk business processes
✦ Consolidating information for throughput analysis, capacity planning, post-processing
operational or security audits, and workload analysis
✦ Reducing the risk of errors associated with manual system administration, including
eliminating individual server logon to view activity, and the need to separately configure each
server for error and exception notifications
Sterling Control Center is available for purchase as a separate product. Contact your Sterling
Commerce representative to learn more about Sterling Control Center.

Connect:Direct Browser User Interface

Connect:Direct Browser User Interface allows you to build, submit, and monitor Connect:Direct
Processes from an Internet browser, such as Microsoft Internet Explorer.
You can also perform Connect:Direct system administration tasks, such as viewing and changing
the network map or initialization parameters, from Connect:Direct Browser. The specific
administration tasks that you can perform depend on the Connect:Direct platform that your browser
is signed on to and your security level.
Connect:Direct Browser is distributed on CD-ROM with Connect:Direct for z/OS, Connect:Direct
for Windows, Connect:Direct for UNIX, and Connect:Direct for HP NonStop. It can also be
downloaded from the Sterling Commerce Web site. Connect:Direct Browser is installed on a Web
server and can be accessed by administrators and users through a URL. The following example
shows the page used to graphically build a Process:

To learn more about Connect:Direct Browser, see the documentation on the Connect:Direct
Browser CD-ROM or available online from the Sterling Commerce Documentation Library.

Connect:Direct for UNIX User’s Guide 11

Chapter 1 About Connect:Direct for UNIX

Connect:Direct Concepts
This section introduces concepts and definitions to help you understand system operations.

Local and Remote Nodes

Each data transfer involves a local and a remote node. The two servers (local and remote) function
together to perform the work. Either Connect:Direct node can initiate the work.
Local and remote node connections are set up in the network map file. Refer to the Maintaining the
Network Map File chapter in the Connect:Direct for UNIX Administration Guide for a description
of the network map file.
Connect:Direct must be installed on each node. When Connect:Direct establishes a session between
the local node and remote node, the node that initiates the session has primary control (PNODE).
The other serves as the partner and has a secondary function (SNODE). The node that initiates the
session has primary control, regardless of the direction of information flow. The Process can specify
work destined for either the local or remote node. When Connect:Direct establishes a session, the
two nodes work together to transfer the information.

Processes
The Connect:Direct Process language provides instructions for transferring files, running programs,
submitting jobs on the adjacent node, and altering the sequence of Process step execution. You can
include one or more steps in a Process. A Process consists of a Process definition statement (Process
statement) and one or more additional statements. Parameters further qualify Process instructions.
The following table lists Process statements and their functions:

Process Statement Function

copy Copies files from one node to another.

conditionals Alters the sequence of Process execution based on the completion code of
previous steps with the if, then, else, eif (end if), goto, and exit
statements.

process Defines general Process characteristics.

run job Enables you to specify UNIX commands in a Process. The Process does
not wait until the job has finished running before executing the next step in
the Process.

run task Enables you to specify UNIX commands in a Process. The Process waits
until the job has finished running before executing the next step in the
Process.

submit Starts another Connect:Direct Process to either the local or remote node
during execution of a Process.

pend Marks the end of a Connect:Direct for UNIX Process.

12 Connect:Direct for UNIX User’s Guide

 Connect:Direct Concepts

Following is a sample Process:

ckpt01 process snode=unix.node

step01 copy from (
file=file1
snode
)
ckpt=1M
to (
file=file2
disp=new
pnode
)
pend;

Refer to the Connect:Direct Processes Web site at

http://www.sterlingcommerce.com/documentation/processes/processhome.html for instructions on
building a Process.

Transmission Control Queue

The Transmission Control Queue (TCQ) controls when Processes run. Connect:Direct stores
submitted Processes in the TCQ. The TCQ is divided into four logical queues: Execution, Wait,
Timer, and Hold. Processes are run from the Execution queue.
Connect:Direct places a Process in the appropriate queue based on Process statement parameters,
such as the hold, retain, and startt parameters.
Connect:Direct runs Processes based on their priority and when the Process is placed in the
Execution queue. Processes will run first based on their submitted date, and higher priority
Processes are selected for execution ahead of Processes with a lower priority. You can access the
queues and manage the Processes through Connect:Direct commands.
Refer to the Connect:Direct for UNIX User’s Guide for more information on scheduling Processes
in the TCQ.

Commands
You use Connect:Direct commands to submit Processes to the TCQ. You can also use
Connect:Direct commands to perform the following tasks:
✦ Manage Processes in the queue
✦ Monitor and trace Process execution
✦ Produce reports on Process activities
✦ Stop Connect:Direct operation

Connect:Direct for UNIX User’s Guide 13

Chapter 1 About Connect:Direct for UNIX

The following table lists the commands and their functions:

Command Function

change process Changes the status and modifies specific characteristics of a nonexecuting
Process in the TCQ.

delete process Removes a nonexecuting Process from the TCQ.

flush process Removes an executing Process from the TCQ.

trace Runs Connect:Direct traces.

select process Displays or prints information about a Process in the TCQ.

select statistics Displays or prints statistics in the statistics log.

stop Stops Connect:Direct operation.

submit Submits a Process for execution.

For example, the following command submits the Process called onestep to the TCQ with a hold
status of yes:

Direct> submit file=onestep hold=yes;

Network Map
During the transfer of data, the Connect:Direct server where the Process is submitted is the primary
node and the secondary node is the remote node (partner). Connect:Direct identifies the remote
nodes that the local node is able to communicate with through the use Connect:Direct network map
(or netmap).
The network map includes the names of all the remote nodes that the Connect:Direct local node can
communicate with, the paths to contact those remote nodes, and characteristics of the sessions for
communication.
The remote Connect:Direct nodes also have network maps for their remote nodes. The following
sample displays the corresponding network map entries of UNIX-Dallas, z/OS-Miami, and
UNIX-Houston:

Connect:Direct for UNIX

UNIX-Dallas

Remote Nodes:
z/OS-Miami
UNIX-Houston

Connect:Direct for z/OS Connect:Direct for UNIX

z/OS-Miami UNIX-Houston
Remote Nodes: Remote Nodes:
UNIX-Dallas UNIX-Dallas
. .
. .
. .

14 Connect:Direct for UNIX User’s Guide

 Connect:Direct Concepts

User Authorization
Connect:Direct can authorize local and remote users to perform certain Connect:Direct tasks. In
order to use Connect:Direct, each user must have a record defined in the user authorization file,
called userfile.cfg. Each local user must have a record in the user authorization file, and remote
users may be mapped to a local user ID in a proxy relationship.
To provide a method of preventing an ordinary user from gaining root access through
Connect:Direct for UNIX, a second access file called the Strong Access Control (SACL) file is
created when you install Connect:Direct and is named sysacl.cfg. The root:deny.access parameter,
which is specified in the sysacl.cfg file, allows, denies, or limits root access to Connect:Direct for
UNIX. If the SACL file is deleted or corrupted, access to Connect:Direct is denied to all users.
For more information about specifying user authorizations in the userfile.cfg and the sysacl.cfg
files, see Maintaining Access Information Files in the Connect:Direct for UNIX Administration
Guide.

Process Restart
Several facilities are provided for Process recovery after a system malfunction. The purpose of
Process recovery is to resume execution as quickly as possible and to minimize redundant data
transmission after a system failure. The following Connect:Direct facilities are available to enable
Process recovery:
✦ Process step restart—As a Process runs, the steps are recorded in the TCQ. If a Process is
interrupted for any reason, the Process is held in the TCQ. When you release the Process to
continue running, the Process automatically begins at the step where it halted.
✦ Automatic session retry—Two sets of connection retry parameters are defined in the remote
node information record of the network map file: short-term and long-term. If you do not
specify a value for these parameters in the remote node information record, default values are
used from the local.node entry of the network map file. The short-term parameters allow
immediate retry attempts. Long-term parameters are used after all short-term retries are
attempted. Long-term attempts assume that the connection problem cannot be fixed quickly
and retry attempts occur after a longer time period, thus saving the overhead of connection
retry attempts.
✦ Checkpoint restart—This feature is available with the copy statement.
Checkpoint restart can be explicitly configured within a copy step through the ckpt parameter.
Refer to the Connect:Direct Processes Web site at
http://www.sterlingcommerce.com/documentation/processes/processhome.html. If it is not
configured in the copy step, it can be configured in the Initparms through the ckpt.interval
parameter. (See Maintaining the Initialization Parameters File in the Connect:Direct for
UNIX Administration Guide for more information on this parameter.)
✦ Run Task restart—If a Process is interrupted when a run task on an SNODE step is executing,
Connect:Direct attempts to synchronize the previous run task step on the SNODE with the
current run task step. Synchronization occurs in one of the following ways:
Š If the SNODE is executing the task when the Process is restarted, it waits for the task to
complete, and then responds to the PNODE with the task completion status. Processing
continues.
Š If the SNODE task completes before the Process is restarted, it saves the task results.
When the Process is restarted, the SNODE reports the results, and processing continues.

Connect:Direct for UNIX User’s Guide 15

Chapter 1 About Connect:Direct for UNIX

If synchronization fails, Connect:Direct reads the restart parameter in the run task step or the
initialization parameters file to determine whether to perform the run task step again. The
restart parameter on the run task step overrides the setting in the initialization parameter.
For example, if the SNODE loses the run task step results due to a Connect:Direct cold restart,
Connect:Direct checks the value defined in the restart parameter to determine whether to
perform the run task again.

Note: Run task restart works differently when Connect:Direct runs behind a connection load balancer.
For more information on the considerations you need to know when running Connect:Direct in
a load balancing environment, see the Connect:Direct for UNIX Release Notes, Connect:Direct
for UNIX Administration Guide, and the Connect:Direct for UNIX Getting Started Guide.

✦ Interruption of Process activity when the SNODE is a Connect:Direct for UNIX node—When
the SNODE is a Connect:Direct for UNIX node and the PNODE interrupts Process activity by
issuing a command to suspend Process activity, deleting an executing Process, or when a link
fails or an I/O error occurs during a transfer, the Process is placed in the Wait queue in WS
status.
If Process activity does not continue, you must manually delete the Process from the TCQ.
Refer to the Connect:Direct for UNIX User’s Guide for command syntax and parameter
descriptions for the delete process command.

Note: You cannot issue a change process command from the SNODE to continue Process activity;
the Process can only be restarted by the PNODE, which is always in control of the session.

Archive Statistics Files

Connect:Direct provides a utility to archive and purge statistics files. When you configure
Connect:Direct, you identify when to archive a statistics file by setting the parameter, max.age, in
the stats record of the initialization parameters file. The max.age parameter defines how old a
statistics file must be before you want to archive the file.
Once a day, the script called statarch.sh is started. This script identifies the statistics files that are
equal to the max.age. It then runs the tar command and the compress command to create a
compressed archived file of all the statistics records that match the max.age parameter. Once the
statistics files are archived, these files are purged. For files archived on a Linux computer, the
archived statistics files have the .gz suffix since these files are compressed with the gzip format.
Archived files on all other UNIX platforms have the .Z suffix to indicate they are compressed using
the compress format.
The archived files are stored in the directory where the statistics files and TCQ are stored. The shell
script, statarch.sh, is located in the ndm/bin directory. If necessary, modify the script to customize
it for your environment.
If you want to restore statistics files that have been archived, run the statrestore.sh script. It uses
the uncompress and tar commands to restore all the statistics files in the archive. You supply two
arguments to the statrestore command. The first argument is the directory path where the statistics
files are located and the second argument identifies the archived file name followed by as many
archived file names as you want to restore.

16 Connect:Direct for UNIX User’s Guide

 Connect:Direct Concepts

Below is a sample statrestore command:

qa160sol: ./statrestore.sh /export/home/users/cd4000/ndm/bin archive1

After files are restored, the statistics records can be viewed using the select statistics command.

Sample Processes, Shell Scripts, and API Programs

Connect:Direct provides sample Processes and shell scripts in d_dir/ndm/src, where d_dir indicates
the destination directory of the Connect:Direct software. You can create similar files with a text
editor. In addition, instructions for creating sample Processes and shell scripts are in the README
file in the same directory.
The following table displays the file names of sample Processes. Modify the Processes as required.

File Name Type of Process

cpunx.cd copy

rtunx.cd run task

rjunx.cd run job

sbunx.cd submit

The following table displays the file names of sample shell scripts. Modify the shell scripts as
required.

File Name Type of Shell Script

selstat.sh select statistics

send.sh send

recv.sh receive

wildcard send multiple files to a PDS

statarch.sh archive statistics files

statrestore.sh restore statistics files that have been archived

lcu.sh launch the Local Connection Utility tool

spadmin.sh launch the Secure+ Option Admin Tool

spcli.sh launch the Secure+ Option CLI (SPCLI)

spcust_sample1.sh configure Secure+ Option for the STS protocol

spcust_sample2.sh configure Secure+ Option for the STS protocol

spcust_sample3.sh configure Secure+ Option to use the SSL or TLS protocol

Connect:Direct for UNIX User’s Guide 17

Chapter 1 About Connect:Direct for UNIX

The following table displays the names of sample programs:

Program Name Description

apicheck.c This program submits a Process to copy a file to a remote system.

MAXDELAY is used in this example, which means that the program will
not finish execution until the file has been transferred. A standard c
compiler is used to compile this module.

apicheck.C Same as apicheck.c, except that it is compiled with one of the C++
compilers listed in the Connect:Direct for UNIX User’s Guide.

exit_skeleton.c This program is a skeleton of a user exit program that works in

conjunction with Connect:Direct for UNIX. It demonstrates usage of all
three user exits.

exit_skeleton.C Same as exit_skeleton_c, except that it is compiled with one of the C++
compilers listed in the Connect:Direct for UNIX User’s Guide.

exit_sample.c This is the same program as the skeleton user exit program, except that
the security exit is demonstrated with code that approximates
PassTicket functionality.

sdksample.C This program exercises various commands using the SDK interface to
Connect:Direct for UNIX.

Connect:Direct Files
This section describes the configuration files, illustrates the directory structure of Connect:Direct,
and lists the individual files that are installed.

Connect:Direct for UNIX Configuration Files

Connect:Direct creates the following configuration files during installation and customization.
These files are required for the Connect:Direct server to operate correctly.

Configuration File Description

Initialization parameters file Provides information to the server to use at start up. During the
installation, you identify the settings necessary for the initialization
parameters file.

User authorization information Contains the local user information and remote user information record
file types. You customize this file during installation to map remote user IDs
to local user IDs and create remote user information records in the user
authorization information file.

18 Connect:Direct for UNIX User’s Guide

 Connect:Direct Files

Configuration File Description

Strong access control file Improves the security of Connect:Direct for UNIX and allows, denies, or
limits root access control. This file is created when you install
Connect:Direct. If the file is deleted or corrupted, access to
Connect:Direct is denied to all users.

Network map file Describes the local node and other Connect:Direct nodes in the network.
You can define a remote node record for each node that Connect:Direct
for UNIX communicates with.

Server authentication key file Verifies client API connection requests. Only verified clients are granted
a connection.

Client configuration file Identifies the port and host name used by a client to connect to
Connect:Direct.

Client authentication key file Identifies Connect:Direct servers that a Connect:Direct client connects
to. You can have multiple entries for multiple servers.

Connect:Direct for UNIX Directory Structure

The following figure illustrates the Connect:Direct for UNIX directory structure. The directory tree
starts at d_dir/, the destination directory where the software is installed. This directory structure
provides for multiple nodes on the same network and possibly on the same computer. The directory
structure organization enables you to share Connect:Direct programs, such as cdpmgr and
ndmcmgr. If multiple nodes exist, each node must have its own d_dir/ndm/cfg/cd_node/ directory
structure for configuration files, where cd_node is the Connect:Direct node name.

Connect:Direct for UNIX User’s Guide 19

Chapter 1 About Connect:Direct for UNIX

Note: The secure+ directory is available only when Secure+ Option is purchased and installed.

d_dir/

ndm/ work/ cd_node etc/

stats
traces

src/

lib/
README cfg/
bin/ apicheck.c security/ secure+/ include/ xlate/ man1/ SACL/
example
files
cliapi/ certificates/
ndmapi.a ndmapi.h
libcd2g.so (not HP) user_exit.h ndmmsg.1
libcd2g.sl (HP only) trusted.txt user_exit2.h ndmxlt.1
libcdsna.so (not HP) cdunxsdk.h ndmpmgr.1
libcdsna.sl (HP only) export/ cdpmgr.1
libcdsnpsna.so ndmapi.cfg
libcdsp.so
libcdspsrvr.so import/ sysacl.cfg
libcdspsssl.so cd_node/
log/ default_recv.xlt
default_send.xlt

ndmcmgr locks/
cdpmgr cdcust
ndmpmgr ttlflst1.0
ndmsmgr nodes/ svcflst1.0
ndmcli cliflst1.0
direct cdver
ndmproc keys.client cdsnacfg (AIX LU6.2 only)
ndmproc.awk keys.server snaver.sh (AIX LU6.2 only)
ndmstat tcq_convert
ndmstat.awk template (Brixton SNA only)
ndmmsg diskfree
ndmxlt diskfree.so
ndmauths cliapi
initparm.cfg hostid.sh
ndmauthc snmpflst1.0
apnotify netmap.cfg
userfile.cfg cfg.convert
cdcustrpt spcust_sample1.sh
cdsacomp msgfile.cfg
msgfile.idx spcust_sample2.sh
cdstatm spcust_sample3.sh
cfgcheck license.key
ndmumgr
cdmsgutil
initcnvt
statarch.sh
statrestore.sh
sample.cd
ndmview
ndmview.awk
initcnvt
Install.bin
lcu.jar
lcu.sh
ohj-jewt.jar (Secure+ only)
runjar.jar (Secure+ only)
SecureOHelp.jar (Secure+ only)
SPAdmin.jar (Secure+ only)
spadmin.sh (Secure+ only)
SPCli.jar (Secure+ only)
CPCliMessages.properties (Secure+
only)
spcli.sh (Secure+ only)
Cipher.txt (Secure+ only)
help4.jar (Secure+ only)

20 Connect:Direct for UNIX User’s Guide

 Connect:Direct Documentation

Note: See the following figure to view the work directory for a node.

A d_dir/work/cd_node directory is created for each node. The following figure displays the work
directory for multiple nodes and illustrates the working files created for each node, such as TCQ
files:

d_dir/

work/
ndm/

cd_node_1 cd_node_2 cd_node_3 cd_node_n

TCQ, statistics file, TCQ, statistics file,

transient files transient files

TCQ, statistics file, TCQ, statistics file,

transient files transient files

Connect:Direct Documentation
Note: See the previous figure for details on the ndm directory structure.

See Connect:Direct for UNIX Release Notes for a complete list of the product documentation.

About This Guide

Connect:Direct for UNIX User’s Guide is for programmers and network operations staff who use
Connect:Direct for UNIX.
This guide assumes knowledge of the UNIX operating system, including its applications, network,
and environment. If you are not familiar with the UNIX operating system, refer to the UNIX library
of manuals.

Connect:Direct for UNIX User’s Guide 21

Chapter 1 About Connect:Direct for UNIX

Task Overview
The following table guides you to the information required to perform Connect:Direct tasks:

Task Reference

Understanding Connect:Direct Chapter 1, About Connect:Direct for UNIX

Understanding the parameters required to invoke the Chapter 2, Controlling and Monitoring Processes
Command Line Interface (CLI) to submit Processes
and commands

Understanding the TCQ and the commands necessary Chapter 3, Process Queuing
to manage Processes in the queue

Understanding and using Connect:Direct utilities Chapter 4, Using Connect:Direct Utilities

Understanding function calls necessary to write custom Chapter 5, Writing Custom Programs
programs to use with Connect:Direct

Understanding user exits and user exit function calls to Chapter 6, Writing User Exits
use with Connect:Direct

22 Connect:Direct for UNIX User’s Guide

 Chapter 2

Controlling and Monitoring Processes

This chapter provides instructions on using the Command Line Interface (CLI) to submit Processes
and commands.

Note: You can also use the Connect:Direct Browser User Interface to perform some of the procedures in
this chapter. To learn more about the Connect:Direct Browser, see the user’s guide on the
Connect:Direct Browser CD-ROM or available online from the Sterling Commerce Documentation
Library.

Using the Command Line Interface

The Command Line Interface (CLI) enables you to submit Connect:Direct Processes and
commands from a native command line environment. This section describes the commands used
during CLI operation.

Starting the CLI

Perform the following steps to start the CLI:
1. If you have not defined the NDMAPICFG environment variable, type the following command
for the appropriate shell, where d_dir is the path to the Connect:Direct subdirectory.

Note: You must set the NDMAPICFG environment variable before you can execute the
cfgCheck utility. For more information about cfgCheck, see Validating Configuration
Files on page 83.

Š In the C shell:

% setenv NDMAPICFG d_dir/ndm/cfg/cliapi/ndmapi.cfg

Connect:Direct for UNIX User’s Guide 23

Chapter 2 Controlling and Monitoring Processes

Š In the Bourne or Korn shell:

$ NDMAPICFG=d_dir/ndm/cfg/cliapi/ndmapi.cfg
$ export NDMAPICFG

2. Type the following command to invoke Connect:Direct CLI. Type options as required:

$ direct [-P string -s -t n -e nn -n name -p nnnnn -x -r -h -z]

Refer to the following table for a description of the command options and sample command
entries:

Option Description Value Sample Command

Entry

-P Identifies the custom string to use at text string $ direct -PNewPrompt

the command line prompt. Up to 32 characters. $ direct -P”Test CD on
If the prompt string includes spaces Medea”
or special characters, enclose it in
single or double quotation marks.
The prompt string can also be
specified in the ndmapi.cfg file. If a
prompt string is specified on the
command line and in the
ndmapi.cfg file, -P takes
precedence.
When the default prompt (“Direct”)
is overridden, the new prompt string
is shown at the command line
prompt and in the welcome banner
display.

-s Suppresses standard output. Use none $ direct -s

this option to view only the
completion status of a command.

24 Connect:Direct for UNIX User’s Guide

 Using the Command Line Interface

Option Description Value Sample Command

Entry

-t n Enables the CLI/API trace option. 1|2|4 $ direct -t 4

The level number, n, identifies the Specify one of the
level of detail in the trace output. following level numbers:
1—Provides function entry
and function exit. This is
the default.
2—Provides function entry
and exits and basic
diagnostic information,
such as displaying values
of internal data structures
at key points in the
execution flow.
4—Enables a full trace. All
diagnostic information is
displayed.

-e nn Defines the error level above which 0 | 4 | 8 | 16 $ direct -e 16

the CLI automatically exits. If the Valid values in the error
returned error code is greater than level code are:
the error level specified, the CLI
0—Indicates successful
automatically exits.
completion.
Use this command within shell
4—Indicates warning.
scripts.
8—Indicates error.
This parameter prevents unwanted
execution of commands following a 16—Indicates catastrophic
command that generates an error error.
above the specified level.
When the CLI terminates, it returns
a UNIX exit code that can be tested
by the shell.

-n name Identifies the host name of the Connect:Direct host name $ direct -n hostname
computer where the Connect:Direct
server (PMGR) is running.
Note: Invoking direct with -p or
-n overrides the settings
in the ndmapi.cfg file.

-p nnnnn Identifies the communications port 1024–65535. The format $ direct -p 2222
number for the Connect:Direct is nnnnn.
node.
Note: Invoking direct with -p or
-n overrides the settings
in the ndmapi.cfg file.

-x Displays command input on none $ direct -x

standard out. Use this command
when debugging scripts.

Connect:Direct for UNIX User’s Guide 25

Chapter 2 Controlling and Monitoring Processes

Option Description Value Sample Command

Entry

-r Makes the Process number none $direct -r | grep

available to user-written shell “_CDPNUM_”
scripts. The CLI displays a special
string, _CDPNUM_ followed by a
space, followed by the Process
number.

-h Displays command usage none $ direct -h

information if a Connect:Direct
command is typed incorrectly.

-z Appends a newline character after none $ direct -z

a prompt.

Using Job Control

Connect:Direct enables you to switch the CLI Process between the foreground and the background
in shells that support job control. This capability enables you to edit the text of saved Processes,
issue UNIX commands, and resolve Process errors without exiting and reentering the CLI. Use the
following commands to switch the CLI Process:
✦ Press the suspend character (Control-Z) to stop or suspend the CLI Process.
✦ Issue the fg command to move the CLI Process to the foreground.

Note: If you experience problems with job control, contact your system administrator for suggestions
on additional UNIX commands to use.

Using History with the CLI

Connect:Direct enables you to use the history commands available with UNIX. History commands
do not need the semicolon (;) at the end of the command. The following table lists the available
history commands:

Command Description

!! Repeat the last command one time.

!#n Set the number of commands to store in the history buffer. The default history buffer size is
50 commands.

!n Repeat command number <n> in the history buffer.

!<string> Repeat command beginning with the string <string>.

!? List the contents of the history buffer.

26 Connect:Direct for UNIX User’s Guide

 Guidelines for Using Connect:Direct Commands

Stopping the CLI

Stop the CLI operation by typing Control-D or quit; at the prompt.

Guidelines for Using Connect:Direct Commands

Refer to the information in this section for guidelines for using Connect:Direct commands:

Command Overview
You control and monitor Connect:Direct Processes using the following commands:

Command Abbreviation Description

submit sub Makes Processes available for execution.

change process cha pro Changes the status and modifies specific characteristics, of a
nonexecuting Process in the TCQ.

delete process del pro Removes a nonexecuting Process from the TCQ.

flush process flush pro Removes an executing Process from the TCQ.

stop stop Stops Connect:Direct and returns control to the operating system.

select process sel pro Monitors both executing Processes and Processes waiting for
execution. You can specify the search criteria and the form in which
the information is presented.

select statistics sel stat Retrieves information from the statistics file. You can specify the
search criteria and the form in which the information is presented.

view process view pro View a Process in the TCQ where the local node is the Pnode.
View process can only display Processes running on the local node
since only the Pnode has the information required to display a
Process.

Note: The CMGR currently limits the size of a Process file to 60K bytes.

Connect:Direct for UNIX User’s Guide 27

Chapter 2 Controlling and Monitoring Processes

Parameter Abbreviations
The following table lists valid abbreviations for commonly used parameters:

Parameter Abbreviation

detail det

quit q

recids rec

release rel

pname pnam, pna

pnumber pnum

sunday sun

monday mon

tuesday tue

wednesday wed

thursday thu

friday fri

saturday sat

today tod

tomorrow tom

Limitations on Using Programs and Scripts

System administrators and other network operations staff can restrict the scripts and UNIX
commands that you can execute with the run task and run job Process statements.
System administrators and other network operations staff can enforce the following limits on the
capabilities you have with Connect:Direct:
✦ The capability to send or receive files; you may be limited either to sending files only or to
receiving files only.
✦ The locations to or from which you can send or receive files; you may be limited to specific
local or remote nodes.
Check with the system administrator for a list of specific restrictions for your user ID.

28 Connect:Direct for UNIX User’s Guide

 Guidelines for Using Connect:Direct Commands

Command Syntax
Use the same command syntax for commands typed at the CLI prompt or used as the command text
parameter for an ndmapi_sendcmd() function. Refer to Writing Custom Programs on page 89, for
details on function calls. The following conventions are used when typing commands:
✦ When selecting a password or user ID, do not use Connect:Direct keywords.
✦ Be aware that user names and file names are case sensitive.
✦ Type an individual command keyword in uppercase, lowercase, or mixed-case characters.
✦ Terminate all commands with a semicolon (;).
✦ When typing commands, type the entire command name or type the first three characters or
abbreviate specific parameters. Refer to the table on page 27 for a list of abbreviations.
✦ Do not abbreviate Process statements and parameters.
✦ File names, group names, user IDs, and passwords are variable length strings and can be any
length.
✦ A Connect:Direct node name is 1–16 characters long. The name of a record in the netmap
describing a remote node is typically the remote Connect:Direct node name, but can be any
string 1–256 characters long. You can also specify a remote node name as an IP address or
hostname and a port number or port name.

Generic
When the word generic is specified as a parameter value in a syntax definition, provide a string that
can include the asterisk (*) and question mark (?) characters. These characters provide a pattern
matching or wildcard facility for parameter values. The asterisk matches zero or more characters,
and the question mark matches any single character. The following sample illustrates the use of the
asterisk and question mark characters:

PNAME = A?PROD5*

The generic Process name specified in the previous sample shows a specification that matches all
Processes beginning with the letter A, followed by any single character in position two with the
string PROD5 in positions three through seven. The asterisk takes the place of zero or more
characters beginning in position eight.

Lists
When (list) is a parameter value, you can specify multiple parameter values by enclosing the group
in parentheses and separating each value with a comma. A list can also include generic values. The
following command illustrates a list:

(pnumber1, pnumber2, pnumber3)

Connect:Direct for UNIX User’s Guide 29

Chapter 2 Controlling and Monitoring Processes

Submitting a Process
Use the submit command to make Processes available for execution and to enable the software to
interpret the Process statements contained in the specified files.

Parameters for submit Command

Parameters specified in the submit command override the same parameters specified on the Process
statement. There are no required parameters. However, if you do not specify a file name for the file
parameter, the text of the Connect:Direct Process must follow the submit command. Following are
the parameters for the submit command:

Parameter Description Values

file The name of the Process file. The file name can file name including the path name
include a path name indicating the location of the
Process.
This parameter must be the first parameter.

class The node-to-node session on which a Process 1|n

can execute. A Process can execute on the class A numeric value from 1 to the value of
specified or any higher session class. The default maximum concurrent local node
class is specified as the sess.default parameter connections (sess.pnode.max). The
of the local.node record in the initialization default value is 1. The value cannot
parameters file. be greater than the maximum number
of local sessions with primary control.

crc Determines if crc checking is performed. This on | off

parameter overrides settings in the initialization on—Turns on crc checking.
parameter, the network map, and the Process.
off—Turns off crc checking. The
Note: The user must be assigned authority to default is off.
change the crc settings in the user
authority file.

hold Determines if the Process is placed in the Hold yes | no | call

queue. yes—Specifies the Process is placed
When a Process is submitted with retain=yes or in the Hold queue in HI status until it is
retain=call, Connect:Direct ignores the hold released by a change process
parameter. command. A Process submitted with
hold=yes is placed on the Hold queue
even if you specify a start time.
no—Specifies that the Process
executes as soon as resources are
available. This is the default.
call—Specifies that the Process is
held until a connection is established
between the remote node and the
local node. At that time, the Process is
released for execution.

30 Connect:Direct for UNIX User’s Guide

 Submitting a Process

Parameter Description Values

maxdelay How long the submit command waits for the unlimited | hh:mm:ss | 0
submitted Process to complete execution. This unlimited—Waits until the Process
parameter is useful when the command is issued completes execution.
by a shell script. When this parameter is specified,
hh:mm:ss—Waits for an interval no
the script waits until the Process completes before
longer than the specified hours,
it continues execution. The return code of the
minutes, and seconds.
Process is stored in the $? variable if you are
using the Bourne or Korn shell and in $status 0—Waits until the Process completes
variable if you are using the C shell, which the execution. If you specify maxdelay=0,
shell script can use to test the results of Process you get the same results as when you
execution. If you do not specify maxdelay, no specify maxdelay=unlimited.
delay occurs.
If the time interval expires, the submit command
returns a warning status code and message ID to
the issuing Process or CLI/API. The Process is
not affected by the time interval expiration and
executes normally.

newname A new Process name that overrides the name in A name up to 256 characters long
the submitted Process.

notify The user E-mail to receive Process completion username@hostname or

messages. This parameter uses the rmail utility user@localhost
available in the UNIX System V mail facility to
deliver the completion messages.
Note: Connect:Direct does not validate the
E-mail address or user ID supplied to
the notify parameter. Invalid E-mail
addresses and failed E-mail attempts
are handled according to the local mail
facilities configuration.

pacct A string containing information about the PNODE. “pnode accounting data” up to 256
Enclose the string in double quotation marks. characters

pnodeid Security user IDs and passwords at the PNODE. id [, pswd]

The pnodeid subparameters can contain 1–64 id—Specifies a user ID on the
alphanumeric characters. PNODE.
pswd—Specifies a user password on
the PNODE.
If you specify pnodeid, you must also
specify id. Identify the ID first and the
pswd last.

prty The priority of the Process in the Transmission 1–15, where fifteen is the highest
Control Queue (TCQ). A Process with a higher priority. The default is 10.
priority is selected for execution before a Process
with a lower priority. The prty value does not affect
the priority during transmission.

Connect:Direct for UNIX User’s Guide 31

Chapter 2 Controlling and Monitoring Processes

Parameter Description Values

retain Determines if Connect:Direct retains a copy of the yes | no | initial

Process in the TCQ. Connect:Direct assigns a yes—Specifies that the system retains
Process number to the Process when it is placed the Process in the Hold queue in HR
in the retain queue. When the Process is run, the status after execution.
Process number assigned to the retain Process is
no—Specifies that the system deletes
incremented by one. For example, if the Process
the Process from the TCQ after
is assigned the Process number of 1445 in the
execution. This is the default.
retain queue, the Process number is 1446 when
the Process is executed. initial—Specifies that the system
retains the Process in the Hold queue
If you specify a start time and set retain=yes, the
in HR status for automatic execution
Process remains in the Timer queue in HR status
every time the Process Manager
and is submitted at the appropriate interval. For
initializes.
example, when startt=(Monday,2:00), the
Process runs each Monday at 2:00 AM. When
startt=(,1:00), the Process runs daily at 1:00 AM.
Connect:Direct for UNIX does not provide a way
to run a Process hourly. To do this, you must use
the UNIX cron utility.
If no start time is identified, you must issue a
change process command to release the
Process for execution.
Do not code the startt parameter when you
specify retain=initial.

sacct Specifies accounting data for the SNODE. Setting “snode accounting data” up to 256
this value in the submit statement overrides any characters. Enclose the string in
accounting data specified in Process. double quotation marks.

32 Connect:Direct for UNIX User’s Guide

 Submitting a Process

Parameter Description Values

snode Identifies the name of the secondary node. Setting name | host name | nnn.nnn.nnn.nnn
this value overrides the snode value in the or
Process statement. The snode parameter is nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnn
required either on the submit command or n:nnnn[;port name | nnnnn]]
Process statement. name—Specifies the node name of
the remote node. The secondary node
name corresponds to an entry in the
network map file.
host name—Specifies the name of the
host computer where the remote
Connect:Direct node is running.
nnn.nnn.nnn.nnn or
nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnn
n:nnnn —Specifies the IP address of
the remote node in IPv4 or IPv6
format: nnn.nnn.nnn.nnn (IPv4) or
nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnn
n:nnnn (IPv6).
[;port number |nnnnn]—Identifies the
communications port. You can only
use this parameter with the host name
or IP address parameters. The nnnnn
value is a decimal number from
1,024–65,535.
For more information on specifying IP
addresses and host names, see the
Specifying IP Addresses, Host
Names, and Ports appendix in the
Connect:Direct for UNIX
Administration Guide.

Connect:Direct for UNIX User’s Guide 33

Chapter 2 Controlling and Monitoring Processes

Parameter Description Values

snodeid Specifies security user IDs and security id [,pswd [,newpswd]]

passwords on the SNODE. The snodeid id—Specifies a user ID on the
subparameters can contain one or more SNODE.
alphanumeric characters.
pswd—Specifies a user password on
If Connect:Direct finds that a Process has no the SNODE. If you specify id, you do
snodeid parameter or defines a snodeid not have to specify pswd. This
parameter and the initialization parameter capability enables the id parameter to
proxy.attempt is set to y, then any password contain a dummy ID to be used for
specified on the snodeid parameter is ignored. A translation to a local ID on the remote
proxy user record is a remote user record in the system.
userfile.cfg, which corresponds to the user name
newpswd—Specifies a new password
specified on the snodeid parameter. If no proxy
value. On certain platforms, the user
user record exists, the snodeid parameter must
password changes to the new value
contain a valid user name and password for a
on the SNODE if the user ID and old
UNIX user who has a corresponding local user
password are correct (refer to
record in the userfile.cfg.
documentation on the specific
When proxy.attempt=n and no snodeid is platform). If the SNODE is a UNIX
defined, Connect:Direct uses the submitting ID node, the password does not change.
and node to find a Remote User Information
If you specify pswd, you must also
record in the User Authorization Information file. If
specify id. If you specify newpswd,
Connect:Direct cannot find a match, then that user
you must also specify pswd. Type the
cannot send or receive files.
values in the order of id, pswd, and
If the initialization parameters file parameter newpswd.
proxy.attempt is set to y, users are not required
to specify a password for the snodeid parameter.
This capability enables the id subparameter to
contain a dummy user ID to be used for
translation to a local user ID on the remote
system. The use of a dummy user ID offers
improved security because neither the sender nor
the receiver are required to use an actual user ID.
Reserved keywords cannot be used in the
snodeid field.

34 Connect:Direct for UNIX User’s Guide

 Submitting a Process

Parameter Description Values

startt Identifies the date, day, and time to start the [date | day] [,hh:mm:ss [am | pm]]
Process. Connect:Direct places the Process in the date—Specifies the day (dd), month
Timer queue in WS (Waiting for Start Time) status. (mm), and year (yy), which you can
The date, day, and time are positional parameters. code as mm/dd/yyyy or mm-dd-yyyy.
If you do not specify date or day, a comma must If you only specify date, the time
precede time. defaults to 00:00:00, which indicates
Do not code the startt parameter when you midnight. The current date is the
specify retain=initial. default.
day—Specifies the day of the week.
Values are today, tomorrow,
yesterday, monday, tuesday,
wednesday, thursday, friday, saturday,
and sunday.
hh:mm:ss [am | pm]—Specifies the
time of day in hours (hh), minutes
(mm), and seconds (ss). You can
specify the hour in either 12- or
24-hour format. If you use 12-hour
format, then you must specify am or
pm. The default is the 24-hour format.
The default value is 00:00:00, which
indicates midnight.
If you specify only the day value, the
time defaults to 00:00:00. This means
that if you submit a Process on
Monday, with monday as the only
startt parameter, the Process does
not run until the following Monday at
midnight.

&symbolic Specifies a symbolic parameter assigned a value. variable string 1

name1 The value is substituted within the Process when variable string 2
&symbolic the symbolic parameter is encountered.
variable string n
name 2 The value for the symbolic parameter must be in
The symbolic name cannot exceed 32
. double quotation marks if it is a keyword or
characters.
. contains special characters. If you want to reserve
&symbolic the double quotation marks when the symbolic
name n name is resolved in the Process, enclose the
double-quoted string in single quotes, for
example:
&filename = “‘filename with spaces’”
The symbolic name itself must not be a subset of
any other symbolic name. (You cannot have, for
example, a symbolic name called &param and
another symbolic name called &parameter in the
same Process.)

Connect:Direct for UNIX User’s Guide 35

Chapter 2 Controlling and Monitoring Processes

Parameter Description Values

tracel Specifies the level of trace to perform for a level = 0 |1 | 2 | 4

Process. Tracing by Process can be turned on in snode | pnode
the submit command or as part of the Process
file=name
definition.
level—Specifies the level of detail
If you identify the snode or pnode immediately
displayed in the trace output. The
after the trace level definition, the trace level is
default is 4.
turned on for all Processes submitted to and from
the node identified. 0—Terminates the trace.
1—The basic level that provides
function entry and function exit.
2—includes level 1 plus function
arguments.
4—Enables a full trace. Basic
diagnostic information, such as
values of internal data structures
at key points in the execution flow,
are displayed.
snode—Specifies to trace only the
SNODE SMGR.
pnode—Specifies to trace only the
PNODE SMGR.
file—Specifies the name of a file
where the trace output is directed. If
you do not specify a file name, the file
is created in the Connect:Direct
working directory with the file name
CMGR.TRC. The length of the name
value is unlimited.

Sample submit Commands

Following are sample submit commands.

Submitting a Process That Runs Every Week

The following command submits the Process named payroll:

submit file=payroll retain=yes startt=monday pacct=“1959,dept-27";

Because retain=yes is specified in this sample, the Process is retained in the TCQ after execution.
The Process starts next Monday at 00:00:00 and runs every Monday thereafter. Process accounting
data is specified for the PNODE. See Chapter 3, Process Queuing, for additional information about
the TCQ.

36 Connect:Direct for UNIX User’s Guide

 Changing Process Parameters

Submitting a Process with a Start Time Specified

The following command submits the Process named copyfil:

submit file=copyfil snode=vmcent startt=(01/01/2008, 11:45:00 am);

Because startt is specified, the Process executes on the first day of January 2008 at 11:45 a.m.

Submitting a Process with No File Value

The following command submits a Process without a file parameter value, but with the Process
statements typed at the CLI command prompt:

Direct> sub do_copy process snode=node1

step01 copy from (
file=data.data
pnode
)
to (
file=b
snode
)
pend ;
Process Submitted, Process Number = 5

Submitting a Process and Turning On Tracing

The following command submits the Process named copy.cdp:

submit file=copy.cdp tracel=4 pnode;

Because tracel is specified and the pnode parameter is included, an SMGR and COMM full trace
is performed on the Process. Trace information is written to the default file SMGR.TRC.

Changing Process Parameters

Use the change process command to modify specified parameters for a nonexecuting Process.
Specify the Processes to be changed by Process name, Process number, secondary node name, and
submitter.
You can change the class, destination node, and priority. You can place a Process on the Hold queue
or release a Process from the Hold queue by issuing a change process command with either the
release or hold=no parameter.
If you submit a Process with a startt parameter, Connect:Direct places the Process on the Timer
queue. If a Process fails, you can move it to the Hold queue by specifying the change process

Connect:Direct for UNIX User’s Guide 37

Chapter 2 Controlling and Monitoring Processes

command with hold=yes. Connect:Direct then places the Process in the Hold queue in HO status.
You can release the Process for execution at a later time.
You can set tracing for an existing Process by setting the tracel parameter to 1, 2, or 4. You can turn
off tracing for a Process by setting trace1 to 0.
Specify at least one of the following search criteria parameters:

Parameter Description Value

pname Locate the Process to be changed name | generic | (list)

by Process name. name—Specifies the Process name, up to 8
The Process name is limited to 8 alphanumeric characters.
characters on Connect:Direct for generic—Specifies a nonspecific value for the
Windows and Connect:Direct for Process name. This generic value, containing
z/OS. pattern-matching characters, evaluates to a list
of zero or more pname strings.
list—Specifies a list of Process names. Enclose
the list in parentheses, and separate each value
with a comma.

pnumber Locate the Process to be changed number from 1–99,999 | (list)

by Process number. number—Specifies the Process number.
Connect:Direct assigns the
list—Specifies a list of Process numbers.
Process number when the
Enclose the list in parentheses, and separate
Process is submitted.
each value with a comma.

snode Locate the Process to be changed remote node specification | generic | (list)
by the secondary node name. This remote node specification—Identifies a specific
parameter can be used to specify remote node name.
a specific remote node, a generic
generic—Specifies a nonspecific value for the
value for matching remote node
remote node name. This generic value,
names (using pattern matching),
containing pattern-matching characters,
or a list of multiple remote node
evaluates to a list of zero or more remote node
names.
names.
The secondary node name
list—Specifies a list of remote node
typically contains the 1–16
specifications. Enclose the list in parentheses,
character remote Connect:Direct
and separate each value with a comma.
node name, but can be any string
up to 256 alphanumeric
characters long. You can also
specify a remote node name as an
IP address or hostname and a
port number.
For more information on
specifying IP addresses and host
names, see the Specifying IP
Addresses, Host Names, and
Ports appendix in the
Connect:Direct for UNIX
Administration Guide.

38 Connect:Direct for UNIX User’s Guide

 Changing Process Parameters

Parameter Description Value

submitter Locate the Processes to be (node specification, userid) | generic | (list)

changed by the node specification node specification, userid—Specifies the node
(the Connect:Direct node name) specification (the Connect:Direct node name)
and user ID of the Process owner. and user ID.
The character length of this
generic—Specifies a nonspecific value for node
parameter is unlimited.
specification and user ID. This generic value,
containing pattern-matching characters,
evaluates to a list of zero or more node
specifications and user IDs.
list—Specifies a list of node specification and
user ID pairs. Enclose the list in parentheses,
and separate each value with a comma.

The optional parameters for the change process command are the following:

Parameter Description Value

class Changes the node-to-node session The default is 1.

on which a Process can execute. A
Process can execute on the class
specified or any higher session
class. The default class is specified
as the sess.default parameter of
the local.node record in the
initialization parameters file.

hold Moves the Process to the Hold or yes | no | call

Wait queue. yes—Places the Process in the Hold queue in
HO status until it is released by another
change process command.
no—Places the Process in the Wait queue in
WC (Waiting for Connection) status; the
Process executes as soon as resources are
available. This is the default.
call—Places the Process in the Hold queue in
HC (Hold for Call) status until the remote node
(SNODE) connects to the local node (PNODE)
or another Process is submitted. At that time,
Connect:Direct releases the Process for
execution

newsnode Specifies a new remote node name new remote node specification
to assign to the Process.

Connect:Direct for UNIX User’s Guide 39

Chapter 2 Controlling and Monitoring Processes

Parameter Description Value

prty Changes the priority of the Process 1–15, where 15 is the highest priority. If you do
on the TCQ. Connect:Direct uses not specify prty, the default is 10.
the prty parameter for Process
selection. A Process with a higher
priority is selected for execution
before a Process with a lower
priority. The prty value does not
affect the priority during
transmission.

release Releases the Process from a held none

state. This parameter is equivalent
to hold=no.

tracel Changes the level of trace to level = 0 | 1 | 2 | 4

perform for a Process. level—Specifies the level of detail displayed in
If you identify the SNODE or the trace output. The default is 4.
PNODE immediately after the trace 0—Terminates the trace.
level definition, the trace level is 1—Is the basic level that provides function
turned on for all Processes entry and function exit.
submitted to and from the node 2 —Includes level 1 plus function
identified. arguments.
4—Enables a full trace. Basic diagnostic
information, such as values of internal data
structures at key points in the execution
flow, are displayed.

The following command changes the remote node name for the Process named cdproc to a new
remote node, paris:

change process pname=cdproc newsnode=paris;

Deleting a Process
Use the delete process command to remove a nonexecuting Process from the TCQ.
You select the Process to delete by Process name, Process number, secondary node name,
submitter, or any combination of the search criteria parameters. Specify at least one of the following
search criteria parameters:

40 Connect:Direct for UNIX User’s Guide

 Deleting a Process

Parameter Description Value

pname Identify the Process to delete by name | generic | (list)

Process name. name—Specifies the Process name up to 8
The Process name is limited to 8 alphanumeric characters long.
characters on Connect:Direct generic—Specifies a nonspecific value for the Process
Windows for and for z/OS. name. This generic value, containing pattern-matching
characters, evaluates to a list of zero or more pname
strings.
list—Specifies a list of Process names. Enclose the list
in parentheses, and separate each value with a
comma.

pnumber Identify the Process to delete by number | (list)

Process number. Connect:Direct number—Specifies the Process number.
assigns the Process number
list—Specifies a list of Process numbers. Enclose the
when the Process is submitted.
list in parentheses, and separate each value with a
Valid Process numbers range
comma (,).
from 1–99,999.

snode Identify the Process to delete by remote node specification | generic | (list)
the secondary node name. This remote node specification—Identifies a specific remote
parameter can be used to specify node name.
a specific remote node, a generic
generic—Specifies a nonspecific value for the remote
value for matching remote node
node name. This generic value, containing
names (using pattern matching),
pattern-matching characters, evaluates to a list of zero
or a list of multiple remote node
or more remote node names.
names.
list—Specifies a list of remote node specifications.
The secondary node name
Enclose the list in parentheses, and separate each
typically contains the 1–16
value with a comma.
character remote Connect:Direct
node name, but can be any string
up to 256 alphanumeric
characters long. You can also
specify a remote node name as
an IP address or hostname and a
port number.
For more information on
specifying IP addresses and host
names, see the Specifying IP
Addresses, Host Names, and
Ports appendix in the
Connect:Direct for UNIX
Administration Guide.

Connect:Direct for UNIX User’s Guide 41

Chapter 2 Controlling and Monitoring Processes

Parameter Description Value

submitter Identify Processes to delete by (node specification, userid) | generic | (list)

the node specification and user ID node specification, userid—Specifies the node
of the Process owner. The specification and user ID.
character length of this parameter
generic—Specifies a nonspecific value for node
is unlimited.
specification and user ID. This generic value,
containing pattern-matching characters, evaluates to a
list of zero or more node specifications and user IDs.
list—Specifies a list of node specification and user ID
pairs. Enclose the list in parentheses, and separate
each value with a comma.

The following command deletes all nonexecuting Processes submitted by user ID cduser on node
dallas:

delete process submitter=(dallas, cduser);

Removing a Process from the Execution Queue

Use the flush process command to remove Processes from the Execution queue. You select the
Process to remove by Process name, Process number, secondary node name, submitter, or any
combination of the search criteria parameters. Specify at least one of the following search criteria
parameters:

Parameter Description Value

pname Locate the Process to remove name | generic | (list)

by Process name. name—Specifies the Process name, up to 8 alphanumeric
The Process name is limited characters.
to 8 characters on generic—Specifies a nonspecific value for the Process
Connect:Direct for Windows name. This generic value, containing pattern-matching
and Connect:Direct for z/OS. characters, evaluates to a list of zero or more pname
strings.
list—Specifies a list of Process names. Enclose the list in
parentheses, and separate each value with a comma.

pnumber Locate the Process to remove number from 1–99,999 | (list)

by Process number. number—Specifies the Process number.
Connect:Direct assigns the
list—Specifies a list of Process numbers. Enclose the list
Process number when the
in parentheses, and separate each value with a comma.
Process is submitted.

42 Connect:Direct for UNIX User’s Guide

 Removing a Process from the Execution Queue

Parameter Description Value

snode Locate the Process to remove remote node specification | generic | (list)
by the secondary node name. remote node specification—Identifies a specific remote
This parameter can be used node name.
to specify a specific remote
generic—Specifies a nonspecific value for the remote
node, a generic value for
node name. This generic value, containing
matching remote node names
pattern-matching characters, evaluates to a list of zero or
(using pattern matching), or a
more remote node names.
list of multiple remote node
names. list—Specifies a list of remote node specifications.
Enclose the list in parentheses, and separate each value
The secondary node name
with a comma.
typically contains the 1–16
character remote
Connect:Direct node name,
but can be any string up to
256 alphanumeric characters
long. You can also specify a
remote node name as an IP
address or hostname and a
port number.
For more information on
specifying IP addresses and
host names, see the
Specifying IP Addresses, Host
Names, and Ports appendix in
the Connect:Direct for UNIX
Administration Guide.

submitter Locate the Processes to (node specification, userid) | generic | (list)

remove by the node node specification, userid—Specifies the node
specification (the specification (the Connect:Direct node name) and user ID.
Connect:Direct node name)
generic—Specifies a nonspecific value for node
and user ID of the Process
specification and user ID. This generic value, containing
owner.
pattern-matching characters, evaluates to a list of zero or
more node specifications and user IDs.
list—Specifies a list of node specification and user ID
pairs. Enclose the list in parentheses, and separate each
value with a comma.

Connect:Direct for UNIX User’s Guide 43

Chapter 2 Controlling and Monitoring Processes

Following are the optional parameters for the flush process command:

Parameter Description Value

force Forcibly terminates an executing yes | no

Process or terminates a Process in an yes—Specifies to forcibly and immediately
orderly fashion as the step completes. terminate the Process. The SMGR also terminates
This parameter is useful if a Process immediately.
is in the executing state and waiting
no—Specifies to terminate the Process in an orderly
for unavailable resources.
fashion as the step completes. The SMGR closes
the statistics file and then terminates. This is the
default.

hold Places the terminated Process in the yes | no

Hold queue where it can be released yes—Specifies to place the Process in the Hold
for re-execution. queue in HS status after the Process is terminated.
no—Specifies to delete the Process from the TCQ
after the Process is terminated. This is the default.

The following command flushes all executing Processes named “Rome” from the Execution queue:

flush process pname=rome force=yes;

The following command flushes all executing Processes on node alma submitted by user ID jones:

flush process submitter=(alma, jones);

Stopping Connect:Direct
Use the stop command to initiate an orderly Connect:Direct shutdown sequence or forcibly
terminate the software. After running the stop command, no new Processes are allowed to run and
no new connections with remote systems are established. Commands can be issued and users can
sign on until the server terminates.
You can specify the force, immediate, quiesce, or step parameters with the stop command.

Note: The force parameter is required when running Connect:Direct with the LU6.2 feature on any
supported platform other than AIX.

44 Connect:Direct for UNIX User’s Guide

 Viewing a Process in the TCQ

Following are the parameters for the stop command:

Parameter Description

force Forcibly terminates Connect:Direct and returns control to the operating system.

immediate Begins an immediate, but orderly shutdown of all activity and terminates Connect:Direct.
The software terminates connections, writes statistics records, closes files, and shuts
down.

quiesce Runs all executing Processes to completion before shutting down Connect:Direct. No
new Processes are started. This is the default value.

step Shuts down Connect:Direct after all currently executing Process steps are complete. The
software writes statistics records, closes files, and shuts down. All active Processes are
retained in the TCQ. Processes restart when the software is re-initialized.

The following command forcibly terminates Connect:Direct and returns control to the operating
system:

stop force;

Viewing a Process in the TCQ

Use the view process command to view Processes in the TCQ when the local node is the Pnode.
You can search by Process name, Process number, queue, secondary node, status, owner of the
Process, or any combination of the search criteria parameters.
You also can specify more than one Process in the search criteria.
There are no required parameters for this command. If you do not specify an optional parameter,
Connect:Direct selects all Processes executing or waiting for execution. Following are the optional
parameters for the view process command:

Parameter Description Value

pname Locate the Process to view by name | generic | (list)

Process name. name—Specifies the Process name, up to 8
The Process name is limited to 8 alphanumeric characters.
characters on Connect:Direct for generic—Specifies a nonspecific value for the Process
Windows and Connect:Direct for name. This generic value, containing pattern-matching
z/OS. characters, evaluates to a list of zero or more pname
strings.
list—Specifies a list of Process names. Enclose the list
in parentheses, and separate each value with a
comma.

Connect:Direct for UNIX User’s Guide 45

Chapter 2 Controlling and Monitoring Processes

Parameter Description Value

pnumber Locate the Process to view by number from 1–99,999 | (list)

Process number. Connect:Direct number—Specifies the Process number.
assigns the Process number
list—Specifies a list of Process numbers. Enclose the
when the Process is submitted.
list in parentheses, and separate each value with a
comma.

queue Specifies the Processes to be all | exec | hold | wait | timer

viewed by the specified queue all—Selects Processes from all queues. This is the
names. default.
exec—Selects Processes from the Execution queue.
hold—Selects Processes from the Hold queue.
timer—Selects Processes from the Timer queue.
wait—Selects Processes from the Wait queue.

snode View the Process by the remote node specification | generic | (list)
secondary node name. This remote node specification—Identifies a specific
parameter can be used to specify remote node name.
a specific remote node, a generic
generic—Specifies a nonspecific value for the remote
value for matching remote node
node name. This generic value, containing
names (using pattern matching),
pattern-matching characters, evaluates to a list of zero
or a list of multiple remote node
or more remote node names.
names.
list—Specifies a list of remote node specifications.
The secondary node name
Enclose the list in parentheses, and separate each
typically contains the 1–16
value with a comma.
character remote Connect:Direct
node name, but can be any string
up to 256 alphanumeric
characters long. You can also
specify a remote node name as
an IP address or hostname and a
port number.
For more information on
specifying IP addresses and host
names, see the Specifying IP
Addresses, Host Names, and
Ports appendix in the
Connect:Direct for UNIX
Administration Guide.

46 Connect:Direct for UNIX User’s Guide

 Viewing a Process in the TCQ

Parameter Description Value

status Specifies the Processes to be EX | HC | HE | HI | HO | HR | HS | PE | WC | WR | WS

viewed by Process status. If you | (list)
do not specify a status value, EX (Execution)—Specifies to select Processes from
information is generated for all the Execution queue.
status values.
HC (Held for Call)—Specifies to select Processes
submitted with hold=call.
HE (Held due to Error)—Specifies to select Processes
held due to a connection error.
HI (Held Initially)—Specifies to select Processes
submitted with hold=yes.
HO (Held by Operator)—Specifies to select Processes
held by a change process command issued with
hold=yes.
HR (Held Retain)—Specifies to select Processes
submitted with retain=yes or retain=initial.
HS (Held Due to Execution Suspension)—Specifies to
select Processes suspended by a flush process
command issued with hold=yes.
PE (Pending Execution)—Specifies to select
Processes submitted with a maxdelay parameter and
assigned PE status by the Process Manager just
before a Session Manager is created to execute the
Process. After the Session Manager initializes, the
Process is placed on the Execution queue and the
status is changed to EX.
WC (Waiting for Connection)—Specifies to select
Processes that are ready for execution, but that all
available connections to the remote node are in use.
WR (Waiting for Restart)—Specifies to select
Processes that are waiting for restart after session
failure.
WS (Waiting for Start Time)—Specifies to select
Processes waiting for a start time. These Processes
are on the Timer Queue.
list—Specifies a list of status values. Enclose the list in
parentheses, and separate each value with a comma.

submitter Locate the Processes to view by (node specification, userid) | generic | (list)
the node specification (the node specification, userid—Specifies the node
Connect:Direct node name) and specification (the Connect:Direct node name) and user
user ID of the Process owner. The ID.
length of this parameter is
generic—Specifies a nonspecific value for node
unlimited.
specification and user ID. This generic value,
containing pattern-matching characters, evaluates to a
list of zero or more node specifications and user IDs.
list—Specifies a list of node specification and user ID
pairs. Enclose the list in parentheses, and separate
each value with a comma.

Connect:Direct for UNIX User’s Guide 47

Chapter 2 Controlling and Monitoring Processes

The following command displays the specified Process number:

view process pnumber=1;

Monitoring the Process Status on the TCQ

Use the select process command to display information about Processes in the TCQ.
The search criteria provide flexibility in selecting Processes. You can search for a Process by
Process name, Process number, queue, secondary node, status, owner of the Process, or any
combination of the search criteria parameters.
You also can specify more than one Process in the search criteria. You can request either a detailed
report about the selected Process or a short report.
There are no required parameters for this command. If you do not specify an optional parameter,
Connect:Direct selects all Processes executing or waiting for execution. Following are the optional
parameters for the select process command:

Parameter Description Value

pname Locate the Process to select by name | generic | (list)

Process name. name—Specifies the Process name, up to 8
The Process name is limited to 8 alphanumeric characters.
characters on Connect:Direct for generic—Specifies a nonspecific value for the Process
Windows and Connect:Direct for name. This generic value, containing pattern-matching
z/OS. characters, evaluates to a list of zero or more pname
strings.
list—Specifies a list of Process names. Enclose the list
in parentheses, and separate each value with a
comma.

pnumber Locate the Process to select by number from 1–99,999 | (list)

Process number. Connect:Direct number—Specifies the Process number.
assigns the Process number
list—Specifies a list of Process numbers. Enclose the
when the Process is submitted.
list in parentheses, and separate each value with a
comma.

queue Specifies the Processes to be all | exec | hold | wait | timer

selected by the specified queue all—Selects Processes from all queues. this is the
names. The default is all. default.
exec—Selects Processes from the Execution queue.
hold—Selects Processes from the Hold queue.
timer—Selects Processes from the Timer queue.
wait—Selects Processes from the Wait queue.

48 Connect:Direct for UNIX User’s Guide

 Monitoring the Process Status on the TCQ

Parameter Description Value

snode Locate the Process by the remote node specification | generic | (list)
secondary node name. This remote node specification—Identifies a specific
parameter can be used to specify remote node name.
a specific remote node, a generic
generic—Specifies a nonspecific value for the remote
value for matching remote node
node name. This generic value, containing
names (using pattern matching),
pattern-matching characters, evaluates to a list of zero
or a list of multiple remote node
or more remote node names.
names.
list—Specifies a list of remote node specifications.
The secondary node name
Enclose the list in parentheses, and separate each
typically contains the 1–16
value with a comma.
character remote Connect:Direct
node name, but can be any string
up to 256 alphanumeric
characters long. You can also
specify a remote node name as
an IP address or hostname and a
port number.
For more information on
specifying IP addresses and host
names, see the Specifying IP
Addresses, Host Names, and
Ports appendix in the
Connect:Direct for UNIX
Administration Guide.

Connect:Direct for UNIX User’s Guide 49

Chapter 2 Controlling and Monitoring Processes

Parameter Description Value

status Specifies the Processes to be EX | HC | HE | HI | HO | HR | HS | PE | WC | WR | WS

selected by Process status. If you | (list)
do not specify a status value, EX (Execution)—Specifies to select Processes from
information is generated for all the Execution queue.
status values.
HC (Held for Call)—Specifies to select Processes
submitted with hold=call.
HE (Held due to Error)—Specifies to select Processes
held due to a connection error.
HI (Held Initially)—Specifies to select Processes
submitted with hold=yes.
HO (Held by Operator)—Specifies to select Processes
held by a change process command issued with
hold=yes.
HR (Held Retain)—Specifies to select Processes
submitted with retain=yes or retain=initial.
HS (Held Due to Execution Suspension)—Specifies to
select Processes suspended by a flush process
command issued with hold=yes.
PE (Pending Execution)—Specifies to select
Processes submitted with a maxdelay parameter and
assigned PE status by the Process Manager just
before a Session Manager is created to execute the
Process. After the Session Manager initializes, the
Process is placed on the Execution queue and the
status is changed to EX.
WC (Waiting for Connection)—Specifies to select
Processes that are ready for execution, but that all
available connections to the remote node are in use.
WR (Waiting for Restart)—Specifies to select
Processes that are waiting for restart after session
failure.
WS (Waiting for Start Time)—Specifies to select
Processes waiting for a start time. These Processes
are on the Timer Queue.
list—Specifies a list of status values. Enclose the list in
parentheses, and separate each value with a comma.

submitter Locate the Processes to select (node specification, userid) | generic | (list)
by the node specification (the node specification, userid—Specifies the node
Connect:Direct node name) and specification (the Connect:Direct node name) and user
user ID of the Process owner. ID.
The length of this parameter is
generic—Specifies a nonspecific value for node
unlimited.
specification and user ID. This generic value,
containing pattern-matching characters, evaluates to a
list of zero or more node specifications and user IDs.
list—Specifies a list of node specification and user ID
pairs. Enclose the list in parentheses, and separate
each value with a comma.

50 Connect:Direct for UNIX User’s Guide

 Monitoring the Process Status on the TCQ

Parameter Description Value

detail Specifies the type of report (short yes | no

or detailed) that Connect:Direct yes—Generates a detailed report.
generates for the selected
no—Generates a short report. This is the default.
Processes.

The following command displays a short report for the specified Process number:

select process pnumber=9 detail=no;

Output from the command is displayed in the following table:

===================================================================================
SELECT PROCESS
===================================================================================
PROCESS NAME NUMBER USER SUBMITTER NODE QUEUE STATUS
-----------------------------------------------------------------------------------
-
PR01 9 root cd.unix.pj EXEC EX
===================================================================================

The following command displays a detailed report for the specified Process number:

select process pnumber=9 detail=yes;

Output from the command is displayed in the following table:

===================================================================================
SELECT PROCESS
===================================================================================
Process Name => pr01 Class => 9
Process Number => 9 Priority => 8
Submitter Node => cd.unix.pj PNODE => cd.unix.pj
Submitter => sub1 SNODE => cd.unix.pj
Retain Process => no Header Type => p

Submit Time => 19:52:35 Schedule Time =>

Submit Date => 05/22/1996 Schedule Date =>

Queue => EXEC

Process Status => EX
Message Text =>
-----------------------------------------------------------------------------------

Connect:Direct for UNIX User’s Guide 51

Chapter 2 Controlling and Monitoring Processes

Determining the Outcome of a Process

Use the select statistics command to examine Process statistics from the Connect:Direct statistics
file. The type of information in the statistics report includes copy status and execution events.
The search criteria provide flexibility in selecting information you want to display. The parameters
used with the select statistics command determine search criteria and the form in which the
information is presented. You can specify records to select by condition code, Process name,
Process number, identification type, category, secondary node, start time, stop time, and submitter
node specification and user ID.
There are no required parameters for this command. If you do not indicate a search requirement with
an optional parameter, Connect:Direct selects all statistics records; however, the volume of records
can be excessive. Following are parameters for the select statistics command:

Parameter Description Value

ccode Selects statistics records operator, nn

based on the completion code operator—Specifies the completion code operator.
operator and return code Following are the valid completion code operators:
values associated with Step
eq or = or == (equal) This is the default.
Termination. You must specify
the return code. ge or >= or => (greater than or equal)
gt or > (greater than)
le or <= or =< (less than or equal)
lt or < (less than)
ne or != (not equal)
The return code is the exit status of the UNIX command or
the Connect:Direct Process or command.
nn—Specifies the return code value associated with Step
Termination.

destfile Selects statistics based on a dest=/path/file name

destination file name. For example:
Note: This parameter can sel stat dest=/sci/payroll/june.payroll;
be abbreviated as
This parameter can be used in combination with the srcfile
dest.
parameter to select statistics based on a source file name
and a destination file name, for example:
sel stat srcf=/sci/accounting/june.payroll
dest=/sci/payroll/june.payroll

52 Connect:Direct for UNIX User’s Guide

 Determining the Outcome of a Process

Parameter Description Value

pname Locate the statistics to select name | generic | (list)

by Process name. name—Specifies the Process name, up to 8 alphanumeric
The Process name is limited characters.
to 8 characters on generic—Specifies a nonspecific value for the Process
Connect:Direct for Windows name. This generic value, containing pattern-matching
and Connect:Direct for z/OS. characters, evaluates to a list of zero or more pname
strings.
list—Specifies a list of Process names. Enclose the list in
parentheses, and separate each value with a comma.

pnumber Locate the statistics to select number from 1–99,999 | (list)

by Process number. number—Specifies the Process number.
Connect:Direct assigns the
list—Specifies a list of Process numbers. Enclose the list in
Process number when the
parentheses, and separate each value with a comma.
Process is submitted.

reccat Specifies whether the CAEV | CAPR | (CAEV, CAPR)

selection of statistics file CAEV—Specifies that the selection of statistics file records
records is based on events or is related to an event, such as a Connect:Direct shutdown.
related to a Process.
CAPR—Specifies that the selection of statistics file records
is related to one or more Connect:Direct Processes.

Connect:Direct for UNIX User’s Guide 53

Chapter 2 Controlling and Monitoring Processes

Parameter Description Value

recids Specifies the statistics file record id | (list)

records to be selected by record id—Selects statistics file records for the specified
record ID. This parameter record ID.
identifies particular types of
list—Specifies a list of Process names. Enclose the list in
statistics records, such as a
parentheses, and separate each value with a comma.
copy termination records or
Connect:Direct initialization Following are the valid record ID values:
event records. APSM—License Management failure generated.
CHGP—The change process command issued.
CRHT—Copyright statement.
COAC—Listen connection enabled for either API or a
remote node.
CSPA—Connect:Direct Secure+ Option failure generated.
CSTP—Child Process stopped.
CTRC—Copy termination record.
CTRM—Child Process terminated.
CUKN—Child Process unknown status.
CXIT—Child Process exited.
DELP—The delete Process command issued.
FLSP—The flush Process command issued.
FMRV—Error occurred in function management.
information receive operation.
FMSD—Error occurred in function management.
information send operation.
GPRC—Error occurred while getting Process.
IFED—The if statement ended.
LSST—The record ID of a step on the local node.
LIEX—License expired.
LWEX—License expires within 14 days.
NINF—Connect:Direct information generated at startup.
NMOP—Network map file opened.
NMPR—The network map is updated through Browser,
Control Center, or KQV Interface.
NUIC—Initialization complete.
NUIS—Initialization started.
NUTC—Termination completed.
NUTS—Termination started.
PERR—Process error.
PFLS—Process flushed.
PRED—Process ended.
PRIN—Process interrupted.
PSAV—Process saved.
PSTR—Process started.
QCEX—A Process moved from another queue to the
EXEC queue.

54 Connect:Direct for UNIX User’s Guide

 Determining the Outcome of a Process

Parameter Description Value

recids QCWA—A Process moved from another queue to the

(cont’d) WAIT queue.
QCTI—A Process moved from another queue to the
TIMER queue.
QCHO—A Process moved from another queue to the
HOLD queue.
RJED—The run job ended.
RNCF—Remote node connection failed.
RSST—The record ID of a step on the remote node.
RTED—The run task ended.
RTSY—Run task restarted. Resyncing with run task that
was executing.
SBED—The submit ended.
SELP—The select Process command issued.
SELS—The select statistics command issued.
SEND—Session ended.
SERR—System error.
SFSZ—Size of the file submitted.
SGON—User signed on using KQV Interface or Command
Line Interface.
SHUD—Shutdown occurred.
SIGC—Signal caught.
SSTR—Session start.
STOP—The stop command issued.
SUBP—The submit command issued.
TRAC—The trace command issued.
TZDI—The time zone of the local node represented as the
difference in seconds between the time at the local node
and the Coordinated Universal Time.
UNKN—Unknown command issued.
USEC—Security check for user ID failed.
USMG—Connect:Direct is shutting down.
XCMM—Command manager (CMGR) messages.
XCPR—Copy receive.
XCPS—Copy send.
XIPT—Communication errors.
XLKL—Low-level TCQ record locking errors.
XMSG—Message sent to user exit.
XPAE—Parsing error occurred when a Process or
command was submitted.
XPAM—Parsing error occurred when a Process or
command was submitted.
XPMC—Process manager (PMGR) connection error
messages.

Connect:Direct for UNIX User’s Guide 55

Chapter 2 Controlling and Monitoring Processes

Parameter Description Value

recids XPML—PMGR statistics log error messages.

(cont’d) XPMP—PMGR error messages when checking permission
on the Connect:Direct programs.
XPMR—PMGR RPC and miscellaneous error messages.
XPMT—PMGR termination error messages.
XRPM—Run task or run job error messages.
XRRF—Relative record file access error messages. File
structure is use for TCQ.
XSMG—Session manager (SMGR) error messages.
XSQF—File access error messages.
XSTA—User exit program started.
XTQG—A single TCQ error message group.
XTQZ—A single TCQ error message group.

snode Locate the statistics file record remote node specification | generic | (list)
by the secondary node name. remote node specification—Identifies a specific remote
This parameter can be used node name.
to specify a specific remote
generic—Specifies a nonspecific value for the remote node
node, a generic value for
name. This generic value, containing pattern-matching
matching remote node names
characters, evaluates to a list of zero or more remote node
(using pattern matching), or a
names.
list of multiple remote node
names. list—Specifies a list of remote node specifications. Enclose
the list in parentheses, and separate each value with a
The secondary node name
comma.
typically contains the 1–16
character remote
Connect:Direct node name,
but can be any string up to
256 alphanumeric characters
long. You can also specify a
remote node name as an IP
address or hostname and a
port number.
For more information on
specifying IP addresses and
host names, see the
Specifying IP Addresses, Host
Names, and Ports appendix in
the Connect:Direct for UNIX
Administration Guide.

56 Connect:Direct for UNIX User’s Guide

 Determining the Outcome of a Process

Parameter Description Value

srcfile Selects statistics based on a srcf=/path/file name

source file name. For example:
Note: This parameter can sel stat srcf=/sci/accounting/june.payroll;
be abbreviated as
This parameter can be used in combination with the destfile
srcf.
parameter to select statistics based on a source file name
and a destination file name, for example:
sel stat srcf=/sci/accounting/june.payroll
dest=/sci/payroll/june.payroll

startt Selects records produced [date | day] [, hh:mm:ss [am|pm]]

both at and since the specified date—Specifies the day (dd), month (mm), and year (yy),
time. The date or day and time which you can code as mm/dd/yyyy or mm-dd-yyyy. If you
are positional. If you do not only specify date, the time defaults to 00:00:00. The current
specify date or day, a comma date is the default.
must precede time.
day—Specifies the day of the week. Values are today,
monday, tuesday, wednesday, thursday, friday, saturday,
and sunday.
hh:mm:ss [am | pm]—Specifies the time of day in hours
(hh), minutes (mm), and seconds (ss). You can specify the
hour in either 12- or 24-hour format. If you use 12-hour
format, then you must specify am or pm. The default is the
24-hour format. The default value is 00:00:00, which
indicates midnight. If you specify only the day value, the
time defaults to 00:00:00.

stopt Specifies that Connect:Direct [date | day] [, hh:mm:ss [am|pm]]

searches for statistics records date—Specifies the day (dd), month (mm), and year (yy),
up to and including the which you can code as mm/dd/yyyy or mm-dd-yyyy. If you
designated date, day, and only specify date, the time defaults to 00:00:00. The current
time positional parameters. If date is the default.
you do not specify date or day,
day—Specifies the day of the week. Values are today,
a comma must precede time.
monday, tuesday, wednesday, thursday, friday, saturday,
and sunday.
hh:mm:ss [am | pm]—Specifies the time of day in hours
(hh), minutes (mm), and seconds (ss). You can specify the
hour in either 12- or 24-hour format. If you use 12-hour
format, then you must specify am or pm. The default is the
24-hour format. The default value is 00:00:00, which
indicates midnight. If you specify only the day value, the
time defaults to 00:00:00.

Connect:Direct for UNIX User’s Guide 57

Chapter 2 Controlling and Monitoring Processes

Parameter Description Value

submitter Locate the statistics records to (node specification, userid) | generic | (list)
select by the node node specification, userid—Specifies the node
specification (the specification (the Connect:Direct node name) and user ID.
Connect:Direct node name)
generic—Specifies a nonspecific value for node
and user ID of the Process
specification and user ID. This generic value, containing
owner. The character length of
pattern-matching characters, evaluates to a list of zero or
the parameter is unlimited.
more node specifications and user IDs.
list—Specifies a list of node specification and user ID pairs.
Enclose the list in parentheses, and separate each value
with a comma.

detail Specifies the type of report yes | no

(short or detailed) that yes—Generates a detailed report.
Connect:Direct generates for
no—Generates a short report. This is the default.
the selected Processes.

The following section illustrates sample detailed and summary reports generated by the select
statistics command.

Sample Detailed Output

The following command generates a detailed report for Process number 9:

select statistics pnumber=9 detail=yes startt=(08/10/2008);

The report consists of all records from August 10, 2008.

A sample statistics output for two steps only is listed in the following section. Use the table in the
recids on page 54 to interpret the Record ID. The Record ID can change for each Process step
displayed. The completion code indicates whether the Process executed successfully or produced
an error condition.
To display the long text of the message, issue the ndmmsg command described in Chapter 4, Using
Connect:Direct Utilities.

Sample Summary Output

The following command generates summary statistics for Process number 9:

sel stat pnumber=9 detail=no startt=(08/10/2008);

The report consists of all records from August 10, 2008.

58 Connect:Direct for UNIX User’s Guide

 Running System Diagnostics

Sample output that describes all Process steps in summary form is displayed in the following table:

===================================================================================
SELECT STATISTICS
===================================================================================
P RECID LOG TIME PNAME PNUMBER STEPNAME CCOD FDBK MSGID
-----------------------------------------------------------------------------------
P PSTR 08/10/2008 09:10:39 PR01 9 0 XSMG200I
P IFED 08/10/2008 09:10:44 PR01 9 0 XSMG405I
P CTRC 08/10/2008 09:10:44 PR01 9 0 XSMG405I
P IFED 08/10/2008 09:10:45 PR01 9 4 XSMG400I
P RTED 08/10/2008 09:10:45 PR01 9 0 XSMG400I
P IFED 08/10/2008 09:10:45 PR01 9 4 XSMG400I
P CTRC 08/10/2008 09:10:45 PR01 9 0 XSMG405I
P CTRC 08/10/2008 09:10:45 PR01 9 8 XSMG405I
P CTRC 08/10/2008 09:10:45 PR01 9 8 XSMG405I
===================================================================================

To avoid lengthy search times when issuing the select statistics command, archive or delete
statistics files regularly. Also, use the startt and stopt parameters to bracket the desired stats as
closely as possible. Execution of a Process generates multiple statistics records. Connect:Direct
closes the current statistics file and creates a new statistics file every midnight. It can also close the
current file before midnight if the file size exceeds the value set for the file.size initialization
parameter. The default file size is 1 megabyte.
Statistics files are in the d_dir/work/cd_node directory. Names of the statistics file are in the format
Syyyymmdd.ext, where yyyy indicates year, mm indicates month, and dd indicates day. The
extension (ext) begins as 001. The extension is incremented by one each time a new statistics file
is created in a single day.

Running System Diagnostics

The diagnostic command, trace, enables you to run system diagnostics and troubleshoot operational
problems. Use the trace command with the appropriate parameter listed in the following table to
enable and disable runtime traces within the Process Manager, Command Manager, and Session
Manager components of the software. For Session Manager traces, you can run a trace for a specific
node.
The Command Manager trace is turned on immediately for the client that issued the trace command.
After the trace command is issued, all clients that make connections are also traced. Session
Manager traces go into effect immediately.

Connect:Direct for UNIX User’s Guide 59

Chapter 2 Controlling and Monitoring Processes

Following are parameters for the trace command:

Parameter Description Value

cmgr To trace the Command level=0 |1 | 2 | 4

Manager. file=name
level—Specifies the level of detail displayed in the trace
output. The default is 4.
0—Terminates the trace.
1—Is the basic level that provides function entry and
function exit.
2—Includes level 1 plus function arguments.
4—Enables a full trace. Basic diagnostic information,
such as values of internal data structures at key
points in the execution flow, are displayed.
file—Specifies the name of a file where the trace output
is directed. If you do not specify a file name, the file is
created in the Connect:Direct working directory with the
file name CMGR.TRC. The length of the name value is
unlimited.

comm To trace the data sent to and level=0 |1 | 2 | 4

received from a remote file=name
Connect:Direct system within
level—Specifies the level of detail displayed in the trace
the Session Manager. You can
output. The default is 4.
set this trace independently
from or in conjunction with the 0—Terminates the trace.
smgr trace. 1—Is the basic level that provides function entry and
function exit.
If you run both the comm and
2—Includes level 1 plus function arguments.
smgr traces, trace output for
4—Enables a full trace that provides basic diagnostic
both traces is directed to the file
information, such as values of internal data
name of the trace last specified.
structures at key points in the execution flow.
file—Specifies the name of a file where the trace output
is directed. If you do not specify a file name, the file is
created in the Connect:Direct working directory with the
file name COMM.TRC. The length of the name value is
unlimited. The default file name is COMM.TRC.

60 Connect:Direct for UNIX User’s Guide

 Running System Diagnostics

Parameter Description Value

pmgr To trace the Process Manager. level=0 |1 | 2 | 4

file=name
level—Specifies the level of detail displayed in the trace
output. The default is 4.
0—Terminates the trace.
1—Is the basic level that provides function entry and
function exit.
2—Includes level 1 plus function arguments.
4—Enables a full trace that provides basic diagnostic
information, such as values of internal data
structures at key points in the execution flow.
file—Specifies the name of a file where the trace output
is directed. If you do not specify a file name, the file is
created in the Connect:Direct working directory with the
file name PMGR.TRC. The length of the name value is
unlimited.

smgr To run the trace for Session level=0 |1 | 2 | 4

Managers created after issuing snode | pnode | tnode
the trace command. Currently
file=name
executing Session Managers
are unaffected. level—Specifies the level of detail displayed in the trace
output. The default is 4.
If you run both the comm and
smgr traces, trace output for 0—Terminates the trace.
both traces is directed to the file 1—Is the basic level that provides function entry and
name of the trace last specified. function exit.
2—Includes level 1 plus function arguments.
4—Enables a full trace that provides basic diagnostic
information, such as values of internal data
structures at key points in the execution flow.
snode—Specifies to trace only the SNODE SMGR.
pnode—Specifies to trace only the PNODE SMGR.
tnode—Identifies the node on which to perform the
trace. If you want to gather trace information for more
than one node, identify more than one node in this
parameter.
file—Specifies the name of a file where the trace output
is directed. If you do not specify a file name, the file is
created in the Connect:Direct working directory with the
file name SMGR.TRC. The length of the name value is
unlimited. The default file name is SMGR.TRC.

The following sample trace commands performs a level 2 trace on the Session Manager for the node
called ath3500ry and writes the output to the file Smgp.trc:

trace smgr pnode tnode=ath3500ry level=2 file=Smgp.trc;

Connect:Direct for UNIX User’s Guide 61

Chapter 2 Controlling and Monitoring Processes

A partial sample trace output is illustrated in the following section. A trace identifies the Process ID
and the function, the month and day, and the time in microseconds. The first column contains the
Process ID. Column two indicates the month and day in the form of MM/DD. Column three
indicates the time in the form of HH:MM:SSSS. The last column indicates the function. An arrow
pointing to the right indicates the function was entered. An arrow pointing to the left indicates the
function was exited.
Some of the functions are indented, which indicates nesting. An indented arrow indicates that the
function was called by the preceding function.

===================================================================================
498 05/18 15:13:0104 cm_sendcmd_1 entered.
498 05/18 15:13:0206 -> ndm_error_destroy
<- ndm_error_destroy: ok
498 05/18 15:13:0506 -> ndm_error_create
<- ndm_error_create: ok
498 05/18 15:13:0708 ndm_cmds_free entered.
ndm_cmds_free exited.
498 05/18 15:13:0801 ->ndm_parser_jdi
498 05/18 15:13:0806 -> ndm_error_create
<- ndm_error_create: ok
498 05/18 15:13:0916 ->Parser: SELPRO
498 05/18 15:13:0926 ->bldexp
<-bldexp: Null argument value,
don’t add.
498 05/18 15:13:1116 ->bldexp
498 05/18 15:13:1136 -> ndm_crit_comp
498 05/18 15:13:1155 ->compile
<-compile
<- ndm_crit_comp: Handle
<-bldexp: ok
.
.
.
===================================================================================

62 Connect:Direct for UNIX User’s Guide

 Chapter 3

Process Queuing

This chapter contains information about the Transmission Control Queue (TCQ), which includes
the following:
✦ A description of the TCQ
✦ Connect:Direct activity scheduling
✦ Progression of a Process through the TCQ, including status values for the Wait, Execution,
Hold, and Timer queues

About the Transmission Control Queue

The TCQ controls Process execution as Connect:Direct operates. After you submit a Process, it is
stored in the TCQ. The TCQ consists of four queues: Execution, Wait, Timer, and Hold.
After you submit a Process, you can monitor the status, modify specific characteristics, and stop
execution by using the appropriate commands. The commands listed in the following table allow
you to perform these tasks:

Command Definition

change process Change the status and modify specific characteristics of a nonexecuting Process
in the TCQ.

delete process Remove a nonexecuting Process from the Wait, Timer, and Hold queues.

flush process Remove an executing Process from the Execution queue.

select process Monitor Processes in the TCQ, including those Processes that are executing.

view process View Processes in the TCQ.

Connect:Direct for UNIX User’s Guide 63

Chapter 3 Process Queuing

Scheduling Connect:Direct Activity

Connect:Direct places a Process in a queue based on the parameters that affect scheduling. You can
specify scheduling parameters in the Process statement or the submit command.
Scheduling parameters are listed in the following section:
✦ retain=yes|no|initial
✦ hold=yes|no|call
✦ startt=[([date|day] [, hh:mm:ss | [am | pm]])
The following table shows how scheduling parameters affect the logical queues.

Scheduling Parameter Queue Comments

None of the scheduling Wait The Process remains in the Wait queue until
parameters specified Connect:Direct establishes a session with the remote
node. After a session is established, the Process moves
to the Execution queue.

retain=yes Hold A copy of the Process executes once, unless you specify
a startt parameter value. Specify a day or time or both for
the Process to start.

retain=no Wait (if no other The Process remains in the Wait queue until
parameters are Connect:Direct establishes a session with the remote
specified) node. The default is no.

retain=initial Hold A copy of the Process remains in the Hold queue and
executes every time the Process Manager is initiated.

retain=yes and hold=no Hold A copy of the Process remains in the Hold queue to be
or hold=call executed when released.

hold=yes Hold You can execute the Process by specifying the change
process command with the release parameter.

hold=no Wait (if no other The default for hold is no.

parameters are
specified)

hold=call Hold The Process remains in the queue until the remote node
starts a session with the local node or another Process
starts a session with that remote node.

startt Timer When the scheduled day or time occur, the Process is
moved to the Wait queue.

Each Process in the TCQ has an associated status value. Each status value has a unique meaning
that is affected by the logical queue in which the Process is placed. Status values for each queue are
shown in the tables in the following sections. You can use the select process command to examine

64 Connect:Direct for UNIX User’s Guide

 Progression of a Process Through the TCQ

that status of Processes in the TCQ. For example, the following command displays all Processes in
the TCQ with execution status:

select process status=EX;

Progression of a Process Through the TCQ

This section describes each logical queue of the TCQ and the progression of a Process through these
queues. The following figure illustrates the four logical queues and their associated parameter
values.

Processes automatically
deleted after completion

Execution submit maxdelay=0

submit
submit retain=no
submit hold=no
Wait

submit startt=(day,date,time)
comm error retry
Timer file allocation error
CRC checking error

submit retain=initial
submit retain=yes
Hold submit hold=yes
submit hold=call

About the Execution Queue

Processes are placed in the Execution queue after Connect:Direct connects to the remote node.
Processes normally come from the Wait queue, but also can be placed in the Execution queue by a
submit command with maxdelay=0 specified.
Processes in the Execution queue can be in execution (EX) status or pending execution (PE) status.
Processes with EX status are exchanging data between two Connect:Direct nodes. Processes with

Connect:Direct for UNIX User’s Guide 65

Chapter 3 Process Queuing

PE status are waiting for Process start messages to be exchanged between the local node and the
remote node. Processes usually have PE status assigned for a very short period of time.
After a Process successfully completes, it is automatically deleted from the Execution queue. A
flush process command with hold=yes moves a Process from the Execution queue and places it in
the Hold queue. When a session is interrupted, the Process moves from the Execution queue to the
Timer queue if retry values are specified. If connection is not made before the retry values are
exhausted or if retry values are not specified, the action taken depends on the
conn.retry.exhaust.action parameter. By default, the Process moves to the Hold queue.
The following table shows the status values for the Execution queue:

Status Comment

PE Pending Execution is the initial queue status when a Process is submitted with
maxdelay=0.

EX Execution status indicates that the Process is executing.

About the Wait Queue

Processes in the Wait queue are waiting for a new or existing connection to become available
between the local node and the remote node.
Processes can come from the Hold queue or the Timer queue. Processes also can be placed in the
Wait queue by a submit command with no parameters specified, submit with retain=no, or submit
with hold=no.
After the connection is made, Processes automatically move to the Execution queue.
The following table shows the status values for the Wait queue:

Status Comment

WC This status indicates the Process is ready to execute as soon as possible, but no
session is available. Other Processes may be executing with the SNODE, and no other
sessions are available. This Process runs as soon as a new session is created or an
existing session becomes available.

WR This status indicates that the Process is in retry status. The number of retries and
intervals between retries is specified in the network map.

WA This status indicates the initial queue status when a Process is submitted without a hold
or retain value. This Process is ready to execute as soon as possible.

WS This status indicates that the Process is waiting for the PNODE to continue the session.

66 Connect:Direct for UNIX User’s Guide

 Progression of a Process Through the TCQ

About the Timer Queue

Processes are placed in the Timer queue by a submit command with the startt parameter specified.
Processes in the Wait for Start Time (WS) status are waiting for the start time to arrive before
moving to the Wait queue. Processes also are placed in the Timer queue in Retry (WC) status if one
of the following error conditions occur:
✦ If a file allocation error occurs when a Process is executing on either the local or the remote
node, and the file allocation error is identified as a condition to retry, the Process is placed in
the Timer queue. The Process is then retried using the short-term and long-term retry
parameter definitions. This capability enables a Process that was unable to execute because a
file that it called was unavailable to be retried at a later time.
✦ If a connection error occurs while a Process is executing, the intelligent session retry facility
places all Processes scheduled for the node, including the executing Process, in the Timer
queue. This capability eliminates the overhead required to retry each of the Processes on the
node even though the connection is lost.
✦ If CRC checking is activated, a Process that generates a CRC error is placed in the Timer
queue.
Connect:Direct automatically tries to execute the Process again based on the number of times to
retry and the delay between retries as specified in the network map parameters.
Processes move from the Timer queue to the Wait queue. A change process command with
hold=yes specified moves the specified Process from the Timer queue to the Hold queue. The
following table shows the status values for the Timer queue:

Status Comment

WR Retry indicates that the Process is in retry status. The number of retries and intervals between
retries is specified in the network map.

WS Wait for Start Time status indicates that the Process was submitted with a start time or date
that has not expired. When startt is reached, the Process is placed in the Wait queue for
scheduling for execution.

HR Held Retain indicates that the Process was submitted with retain=yes or retain=initial specified
and has already executed. The Process can be released later by a change process
command with release specified.

WC This status indicates the Process is ready to execute as soon as possible, but no session is
available. Other Processes may be executing with the SNODE, and no other sessions are
available. This Process runs as soon as a new session is created or an existing session
becomes available.

About the Hold Queue

Processes in the Hold queue are waiting for operator intervention before they progress to the Wait
queue. This queue enables operators of the local node and remote node to coordinate and control
Process execution.

Connect:Direct for UNIX User’s Guide 67

Chapter 3 Process Queuing

Processes are placed in the Hold queue by a submit command with retain=initial, retain=yes, or
hold=yes parameters specified. Processes submitted with hold=call also are placed in the Hold
queue. Processes are moved from the Timer queue to the Hold queue by a change process
command with hold=yes specified. Additionally, Processes are moved from the Execution queue
to the Hold queue by a flush process command with hold=yes specified.
Processes are moved from the Hold queue to the Execution queue by a change process command
with the release parameter specified.
The following table shows the status values for the Hold queue:

Status Comment

HC Held for Call indicates that the Process was submitted with hold=call specified. A
session started from either node causes the Process to be moved to the Wait queue in
WC status. The Process is placed in the Execution queue when the Process is selected
for execution.

HI Held Initially indicates that the Process was submitted with hold=yes specified. The
Process can be released later by a change process command with release or hold=no
specified.

HE Held due to error specifies that a session error or other abnormal condition occurred.

HO Held by Operator indicates that a change process hold=yes was specified.

HR Held Retain indicates that the Process was submitted with retain=yes or retain=initial
specified and has already executed. The Process can be released later by a change
process command with release specified.

HS Held for Suspension indicates that the operator issued a flush process command with
hold=yes specified. The Process can be released later by a change process command
with release specified.

68 Connect:Direct for UNIX User’s Guide

 Chapter 4

Using Connect:Direct Utilities

Connect:Direct for UNIX provides tools and utilities to assist you in the following tasks:
✦ Working With Translation Tables
✦ Accessing Connect:Direct Messages
✦ Using License Key File Notification
✦ Precompressing/Decompressing Files Using the Standalone Batch Compression Utility
✦ Validating Configuration Files
✦ Generating a Configuration Report

Working With Translation Tables

Connect:Direct translates data from one character set code to a different character set code, such as
from ASCII to EBCDIC, based on a character translation table in the d_dir/ndm/xlate directory.
Connect:Direct provides a default character translation table for use during file transfer operations
or you can modify this table using the utility program called ndmxlt.
To create a translation table, either copy the file called /cd_dir/cdunix/ndm/src/def_send.sxlt or
/cd_dir/cdunix/ndm/src/def_recv.sxlt, where cd_dir is the directory where Connect:Direct for
UNIX is installed, and rename it or modify this file. Use a text editor to add the new values to the
table in the file you created. Compile the updated file with the ndmxlt utility. Replace the default
translation table in the d_dir/ndm/xlate with the updated table. Each table is 256 bytes long.

Connect:Direct for UNIX User’s Guide 69

Chapter 4 Using Connect:Direct Utilities

Following is a sample translation table:

# This file contains an example of defining an ASCII-to-EBCDIC translation table and

# then changing it to translate lowercase to uppercase.
#
# Define the ASCII-to-EBCDIC table.
offset=0
00 01 02 03 04 05 06 07 08 05 15 0B 0C 0D 0E 0F
10 11 12 13 3C 15 16 17 18 19 1A 1B 1C 1D 1E 1F
40 5A 7F 7B 5B 6C 50 7D 4D 5D 5C 4E 6B 60 4B 61
F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 7A 5E 4C 7E 6E 6F
7C C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6
D7 D8 D9 E2 E3 E4 E5 E6 E7 E8 E9 AD E0 BD 5F 6D
79 81 82 83 84 85 86 87 88 89 91 92 93 94 95 96
97 98 99 A2 A3 A4 A5 A6 A7 A8 A9 C0 4F D0 A1 7F
80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F
90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F
A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF
B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF
C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 CA CB CC CD CE CF
D0 D1 D2 D3 D4 D5 D6 D7 D8 D9 DA DB DC DD DE DF
E0 E1 E2 E3 E4 E5 E6 E7 E8 E9 EA EB EC ED EE EF
F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF
#
# Change the lowercase characters to uppercase.
offset=61
C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 D7
D8 D9 E2 E3 E4 E5 E6 E7 E8 E9

Each byte stores the character value for the target character set. The source character set is used as
an index into the table. For example, an ASCII blank (Hex 20) would locate the byte at offset Hex
20 in the translation table. If the byte at location Hex 20 contains Hex code 40, that would translate
to an EBCDIC code indicating a blank character.

Creating and Modifying a Translation Table

You can create or modify a translation table tailored to your requirements with the ndmxlt utility
program. To invoke the ndmxlt utility, type the following command at the UNIX prompt:

$ ndmxlt -ssourcefile -ooutputfile [ -rradix] [ -ffiller] -mxlatefile

The parameters for the ndmxlt command are listed in the following section:

Parameter Description Values

-ssourcefile The path and file name of the translation table Path and name of translation
source file. If no value is specified, input is read from table
STDIN.

-ooutputfile The path and file name of the translation table Path and name of translation
output file. output file

70 Connect:Direct for UNIX User’s Guide

 Working With Translation Tables

Parameter Description Values

-rradix The radix or base of the source file input data. All x|d|o
numeric values whether from command line options x—Hexadecimal. This is the
or input data are interpreted based on the radix default.
setting.
d—Decimal
o—Octal
The default is x.

-ffiller A filler byte value. The entire table is initialized to Any keyboard character, number,
this value before the input data is scanned and or special character, plus control
applied to the table. characters entered using a
preceding slash.
For example, “\0” is null.

-m The path and file name of a model translation table. Path and file name of the model
If specified, the model table is read in and then the translation table
input data is scanned and applied to the table. This
capability permits creating a number of different
tables that are variations from a single base table
without having to specify all 256 bytes of input data
for each table.

This section provides examples of how to create a translation table or modify an existing translation
table.

Example—Creating a Translation Table

Perform the following steps to create a sample translation table that changes lowercase characters
to uppercase characters:
1. Make a copy of the sample translation table located at cd_dir/ndm/src/def_send.sxlt.
2. Open the new translation table with a text editor.
3. Add the following lines to the bottom of the table. It should look like the table on page 4-1
when you have added this information.

#
# Change the lowercase characters to uppercase.
offset=61
C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 D7
D8 D9 E2 E3 E4 E5 E6 E7 E8 E9

4. Copy the modified file to cd_dir/ndm/src and name it UpperCaseEBC.sxlt.

5. Compile the new translation table using the following syntax:

ndmxlt -s../src/UpperCaseEBC.sxlt -oUpperCaseEBC.xlt

Connect:Direct for UNIX User’s Guide 71

Chapter 4 Using Connect:Direct Utilities

6. To use this translation table, add the following sysopts parameter to the copy statement:

copy from file=filename

to file=filename
sysopts=":xlate.tbl=pathname/UpperCaseEBC.xlt:"

Example—Modifying a Model Translation Table

Perform the following steps to modify a model translation table. This method, when implemented,
reads the model table and writes it to a new file. It then reads the input data and makes changes to
the table created.
1. Create a file called FourLinesUpperCase.sxlt and add the following lines to the file:

#
# Change the lowercase characters to uppercase.
offset=61
C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 D7
D8 D9 E2 E3 E4 E5 E6 E7 E8 E9

2. Copy the modified file to cd_dir/ndm/src.

3. Type the following command to compile this file and create a translation table called
fourLineUpperCase.xlt:

ndmxlt -s../src/FourLineUpperCase.sxlt -oFourLineUpperCase.xlt -mdef_send.xlt

4. To use this translation table, add the following sysopts parameter to the copy statement:

copy from file=filename

to file=filename
sysopts=":xlate.tbl=pathname/FourLineUpperCase.xlt:"

Using Translation During File Transfer Operations

Translation is specified in the copy statement of a Connect:Direct Process. You can use the default
translation table or create a new table. To use the default translation table, type the following copy
statement:

copy from file=abc to file=xyz sysopts=":xlate=yes:"

To specify a customized table for data translation, include the following sysopts subparameter in
the copy statement, where pathname/filename identifies the translation table:

copy from file=filename

to file=filename
sysopts=":xlate.tbl=pathname/filename:"

72 Connect:Direct for UNIX User’s Guide

 Accessing Connect:Direct Messages

Refer to the UNIX section of the Connect:Direct Processes Web site at

http://www.sterlingcommerce.com/documentation/processes/processhome.html for additional
details concerning translation table specification with a copy statement.

Diagnostics
The following table displays the error messages that are generated by ndmxlt:

Diagnostic Number Description

XXLT001I Invalid directive

XXLT002I Input file open error

XXLT003I Model file open error

XXLT004I Invalid filler value

XXLT005I Invalid offset value

XXLT006I Invalid radix value

XXLT007I Invalid table value

XXLT008I Table data out of bounds

Accessing Connect:Direct Messages

The Connect:Direct message file contains records with text for all messages, including errors and
messages from Connect:Direct servers other than the host server. You can add and delete message
records with a text editor. The message file resides in d_dir/ndm/cfg/cd_node/msgfile.cfg. You can
display message text with the ndmmsg command.

About the Message File Content

The message file is structured much the same way as other Connect:Direct configuration files. Each
record is a logical line in a text file that consists of one or more physical lines. Each record has a
unique name, a message ID, and fields that make up the message text.
The message record definitions provide for symbolic substitution, which permits including actual
file names or other variable information within the text to more specifically identify a problem.
Symbolic variables begin with the ampersand character (&).

Connect:Direct for UNIX User’s Guide 73

Chapter 4 Using Connect:Direct Utilities

The format of Connect:Direct message IDs is listed in the following table:

XxxxnnnI

Where:

X Indicates Connect:Direct
xxx is a 3-character Connect:Direct component identifier
nnn is a 3-digit decimal number
I is the standard, though not required, suffix

Understanding the Message File Record Format

The following example shows the format of the message file record. Each record can be up to 4K
bytes long. Optional parameters and values are in brackets.

message id [long.text detailed message explanation] [mod.name issuing module name] short.text message summary

Following are the parameters for the message file record:

Parameter Description Values

long.text A string that explains the message in detail. A text string

mod.name The name of the source module issuing the message Source module name
ID.

short.text A summary of the message. This field is required. Summary message, up to 72

characters

The following example illustrates a sample message record for XCPS008I.

XCPS008I:\ :mod.name=NUSMCP00.C:\
:short.text=File is not VB datatype.:\
:long.text=File is not variable block. Change sysopts datatype to\
either binary or text to transfer this file.\
\nSYSTEM ACTION-> the copy step failed and CD processing\
continued with the next process step.\
\nRESPONSE-> change the sysopts datatype to either\
binary or text.:\

Displaying Message Text

Use the ndmmsg command to display text in the message file. You can display both short and long
text.
The following command illustrates the format for ndmmsg:

ndmmsg -f msgfname [-l | -s] msgid1 [msgid2 [msgid3 [...]]]

74 Connect:Direct for UNIX User’s Guide

 Using License Key File Notification

Following are the parameters for the ndmmsg command. If you do not specify an l or s parameter,
both short and long text are displayed.

Parameter Description

-f Specifies the name of the message file.

-l Displays the long text of a message.

-s Displays the short text of a message.

Following is a sample ndmmsg command:

ndmmsg -f /usr/ndmunix/msgfile.cfg XCMG000I

Output from the command is displayed in the following example

rc=&rc
fdbk=&fdbk
mod.name=NUCMRG00.C
func.name=ndmapi_sendcmd
short.text=CMGR RPC call returns NULL
long.text=The ndmapi_sendcmd RPC call made by the API to the CMGR returns a NULL
pointer. There is probably an RPC error.
ndm.action=None
user.action=First, check if the ndmcmgr is still running; it could have been killed
accidently. If so, then abort the current CLI and restart the CLI. If the same
problem occurs again, try to increase the value of wait time (if set) in the API
configuration file (ndmapi.cfg).

Using License Key File Notification

The Server (PMGR) checks for a new license.key file every 30 seconds. If the server is busy
because of high cpu usage, you can run the apnotify command to inform the Connect:Direct server
that a new license file should be checked immediately. Following is the format for the apnotify
command:

apnotify [ -t timeout ] [ -f ]

Following are the parameters for the apnotify command:

Parameter Description

-t Set this timeout value to any positive single digit number to wait for a server response.

-f Request for an immediate response.

Connect:Direct for UNIX User’s Guide 75

Chapter 4 Using Connect:Direct Utilities

The following examples illustrate sample output for the apnotify command:

#apnotify
License file update: new license file accepted.

#apnotify -t
Response from Connect:Direct PMGR timed out.
Suggestion: Try again with a higher timeout.

#apnotify
License file update: license file last updated on Fri Aug 6 08:46:28 2003
No changes to the license file since the last update were detected.
A license file reread can be forced by doing an "apnotify -f".

Precompressing/Decompressing Files Using the Standalone

Batch Compression Utility
The Standalone Batch Compression Utility (cdsacomp) enables you to precompress files and then
transfer the precompressed files to remote Connect:Direct nodes using Connect:Direct Processes.
You have the following options for decompressing the files. A file can either be:
✦ Decompressed as it is received by the remote node (available on all Connect:Direct platforms)
✦ Stored on the remote node and later decompressed offline using cdsacomp (available only on
Connect:Direct for UNIX and Connect:Direct for z/OS).
Because cdsacomp can be used offline, it allows you to allocate some of the overhead associated
with compression to non-peak times. For example, if you need to send the same file to several
remote nodes, use this utility so that the file is precompressed only one time. You can also use
cdsacomp to determine how much compression can be achieved for a file without having to transmit
the file.
The cdsacomp utility is located in the Connect:Direct for UNIX /bin directory.

Special Considerations for Using the Standalone Batch Compression Utility

Consider the following when you are using cdsacomp to precompress files:
✦ If you precompress a file with the cdsacomp utility, then you cannot specify any compression
options in your Connect:Direct Process when you copy that file.
✦ You cannot specify data transformations (xlate, codepage, strip blanks, and so on) when
sending a precompressed file with :precompress=yes: sysopts (for on-the-fly decompression).
The following transformation options are available; these options are described in the
parameter table below.
Š -x
Š -p

76 Connect:Direct for UNIX User’s Guide

 Precompressing/Decompressing Files Using the Standalone Batch Compression Utility

Š -s
Š -a
✦ If you precompress a file with the cdsacomp utility on a Connect:Direct for UNIX node, then
you cannot specify a checkpoint interval in your Connect:Direct Process if you decompress
the file as it is received by the remote node.
✦ When you are copying a precompressed file to z/OS without :precomp=yes: (for deferred
decompression):
Š The Copy operation must specify DCB information for the destination file. The physical
block size of the destination file on Connect:Direct for z/OS must match the logical block
size of the precompressed source file on Connect:Direct for UNIX.
Š The logical block size of the source file defaults to 27920 unless overridden by the -b
parameter.

Using the Standalone Batch Compression Utility

To invoke the standalone batch compression utility (cdsacomp), type the following command at a
UNIX prompt:

cdsacomp

Following are the parameters for the cdsacomp utility:

Parameter Description Values

-m Specify which mode to use: precompress or compress | decompress

decompress. This argument is required. The default is compress.

-i Specify the input file to precompress or full or relative path of input file
decompress. This argument is required.

-o Specify the output file to save. If the output file full or relative path of output file
already exists, it is overwritten. This argument is
required.

Connect:Direct for UNIX User’s Guide 77

Chapter 4 Using Connect:Direct Utilities

Parameter Description Values

-z Use this option with “-m compress” to override level, window, memory
default compression values. This argument is level—Compression level. The
optional. range is 1–9. The default is 1.
When decompressing, the values used during 1—Provides the least
compression are used. compression, but is the
fastest.
9—Provides the most
compression, but is the
slowest.
window—The size of the
compression window and history
buffer. Increasing the window
increases the compression, but
uses more virtual memory. The
range is 9–15. The default is 13.
memory—The amount of virtual
memory to allocate. The range is
1–9. The default is 4.
1—Uses the least virtual
memory.
9—Uses the most virtual
memory.

-x Use this option to translate the file. full path to translate table file |
If this parameter is not specified, the file is not relative path to translate table file
translated.
This parameter is mutually exclusive with
-codepage.

-p Use this option to specify codepages for file source codepage, destination
conversion. Default is no codepage translation. codepage
This parameter is mutually exclusive with -xlate.

78 Connect:Direct for UNIX User’s Guide

 Precompressing/Decompressing Files Using the Standalone Batch Compression Utility

Parameter Description Values

-d Specify the datatype of the file. text | binary | VB

When you use “-m compress”, the datatype The default is text.
values result in the following:
✦ text
Š Strips newline characters from each
record
Š Supports -s and -a parameters
Š Uses data attributes of blocksize=23040,
recfm=vb, lrecl=23036, dsorg=ps
✦ binary
Š Uses data attributes of blocksize=23040,
recfm=u, lrecl=0, dsorg=ps
Š Does not support -s and -a parameters
✦ VB
Š Does not support -x, -p, -s, and -a
parameters
Š Uses data attributes of blocksize=23040,
recfm=vb, lrecl=23036, dsorg=ps
When you use “-m decompress”, the datatype
values result in the following:
✦ text
Š Inserts newline characters into each
record
Š Supports the -s parameter
✦ binary
Š Does not support the -s parameter
✦ VB
Š Does not support -x, -p, and -s parameters

-b Specify the block size of the output file. nnnnn

This parameter is valid only when you specify The range is 4096–32760. The
“-m compress” for the compression option. default is 27920.

-s Use this option to strip trailing blanks. y|n

This parameter is valid only when you specify y—yes
“-d text” for the datatype of the file. n—no
The default is y.

Connect:Direct for UNIX User’s Guide 79

Chapter 4 Using Connect:Direct Utilities

Parameter Description Values

-a Use this option to replace zero-length records y|n

with a single, blank character. y—yes
This parameter is valid only when you specify the n—no
following: “-d text” and “-m compress”.
The default is y.
Specify n if the data is copied to
an i5OS or mainframe node.

-h Use this option to display online help for the No values are available for this
utility. parameter.

Example—Precompressing a Text File

In this example, the source file is a text file named source.file which is precompressed into a
destination file named compressed.file. The file is translated using the default translation table,
/home/cd/ndm/xlate/def_send.xlt. Trailing blanks are stripped. Default settings for ZLIB tuning,
checkpoint interval and block size are used.

cdsacomp -m compress
-d text
-i source.file
-o compressed.file
-x /home/cd/ndm/xlate/def_send.xlt
-s y

Example—Precompressing a Text File With Codepage Conversion

In this example, the source file is a text file named zzz.sac which is precompressed into a file named
zzz.txt. The file is converted from EBCDIC-US to ASCII using the codepage option. Default
settings are used for parameters that are not specified.

cdsacomp -m compress
-d text
-i zzz.txt
-o zzz.sac
-p EBCDIC-US,ASCII

80 Connect:Direct for UNIX User’s Guide

 Precompressing/Decompressing Files Using the Standalone Batch Compression Utility

Example—Precompressing a Binary File

In this example, the source file is a binary file named source.file which is precompressed into a
destination file named compressed.file. Default settings are used for parameters that are not
specified.

cdsacomp -m compress
-d binary
-infile source.file
-outfile compressed.file

Example—Decompressing a Text File

In this example, the source file is a precompressed text file named compressed.file which is
decompressed into a destination file named dest.file. The file is translated using the default
translation table, /home/cd/ndm/xlate/def_recv.xlt. Default settings are used for parameters that are
not specified.

cdsacomp -m decompress
-d text
-i compressed.file
-o dest.file
-x /home/cd/ndm/xlate/def_recv.xlt

Examples—csdacomp Command Help

Requesting a summary of cdsacomp command parameters and help options:

cdsacomp -h

Connect:Direct for UNIX User’s Guide 81

Chapter 4 Using Connect:Direct Utilities

Example—Decompressing the File on the Remote Node During the Copy Step

The “precomp=yes” parameter is used when the file was compressed by the cdsacomp utility prior
to this Process. The file is transferred by this Process as a pre-compressed file. It is then
decompressed by special processing as it is received on the remote node.

sample process snode=cdunix1

step01 copy
from
(
file=/home/cd/upload/compressed.file
sysopts=”:precomp=yes:”
pnode
)

to
(
file=/home/cd/download/decompressed.file
snode
disp=rpl
)

pend;

Example—Sending Precompressed File to z/OS and Storing It as Precompressed

The precompressed file is copied to the z/OS node with PNODE sysopts of “datatype=binary”. The
destination file is not decompressed. The DCB settings of the original precompressed file are
preserved on the z/OS node. The specified checkpoint interval will be used during the file transfer.
The file can be decompressed with the z/OS cdsacomp utility.

sample process snode=cdunix1

step01 copy
from
(
file=/home/cd/upload/compressed.file
sysopts=”:datatype=binary:”
pnode
)

chkpt=2M

to
(
file=upload.compressed.file
dcb=(blksize=27920, lrecl=0, dsorg=ps, recfm=u)
snode
disp=(new,catlg)
)

pend;

82 Connect:Direct for UNIX User’s Guide

 Validating Configuration Files

Validating Configuration Files

When you manually edit any of the five text-based Connect:Direct for UNIX configuration files,
the Configuration Checking Utility (cfgCheck) enables you to validate these files offline. The
following files can be validated using this utility: userfile.cfg, initparm.cfg, netmap.cfg,
ndmapi.cfg, and sysacl.cfg.

Note: The Strong Access Control File (sysacl.cfg) will be validated only when the user running the
Configuration Checking Utility is a root user.

By default, cfgCheck is run with no arguments and attempts to find all five of the configuration files
in the current working directory. If all of the Connect:Direct components are not installed, then
some of the files will not be found. For example, if the Command Line Interface (CLI) is installed
but the Connect:Direct server is not installed, only the ndmapi.cfg file will exist in the installation
directory. Therefore, only the ndmapi.cfg file will be validated. When cfgCheck is run with no
arguments, the utility will report that the other configuration files were not found.

Note: Before you can execute cfgCheck, you must set the NDMAPICFG environment variable.
For more information, see Starting the CLI on page 23.

To invoke cfgCheck, type the following command at the UNIX prompt:

$ cfgCheck -v -h -f filename.cfg

The arguments for the cfgCheck command are listed in the following table:

Arguments Description

No arguments When no arguments are specified and cfgCheck is run by a non-root user, it searches
(default) the cfg/ directory for the following configuration files: initparm.cfg, netmap.cfg,
userfile.cfg, and ndmapi.cfg. When a root user runs cfgCheck, the utility also
searches the SACL/ directory to locate the sysacl.cfg file.

-h Prints the help screen and exits.

-t Turns on tracing and prints verbose debug information.

-f filename.cfg Specifies a configuration file name to validate, where filename is the name of one of
the configuration files. You can specify multiple -f arguments. When the -f argument is
used, cfgCheck will not automatically search for other configuration files from the file
specified.
Note: To validate the sysacl.cfg file, you must have root access or have effective
permissions of root.

Connect:Direct for UNIX User’s Guide 83

Chapter 4 Using Connect:Direct Utilities

Generating a Configuration Report

You can generate a report of your system information and Connect:Direct for UNIX configuration
information using the Configuration Reporting Utility (cdcustrpt). Configuration reports can be
generated for the following Connect:Direct components:
✦ Base installation of Connect:Direct for UNIX
✦ Connect:Direct Secure+ Option for UNIX
✦ Connect:Direct UNIX for SWIFTNet
During the Connect:Direct for UNIX installation, cdcustrpt is installed in the <installation>/etc/
directory.

Reporting on the Base Installation

When you use cdcustrpt to generate a report on the base Connect:Direct for UNIX installation, it
reports the following types of system information:
✦ Name and other information of the operating system
✦ Space on file systems
✦ Virtual memory statistics
✦ Contents of the Connect:Direct installation directory
✦ License key information
In addition to reporting system information, cdcustrpt invokes the Configuration Checking Utility
(cfgCheck) to validate the syntax of the five text-based configuration files (if they are available and
if the user has access to the files) and to report on the contents of the configuration files. For more
information on cfgCheck, see Validating Configuration Files on page 83.
To invoke cducustrpt and generate a report of the base installation:
1. Type the following command at a UNIX prompt:

$ cdcustrpt

Note: Default values are computed by the utility based on the location and name of the installed
Connect:Direct for UNIX and are provided in brackets “[ ]”. Press Enter to accept the default values.

2. Type the full path where Connect:Direct is installed and press Enter.
3. Type the full path and name for the report that will be generated and press Enter.

84 Connect:Direct for UNIX User’s Guide

 Generating a Configuration Report

4. The report is generated in the location you specified, and any error messages are displayed as
shown in the following example:

% cdcustrpt
Enter full path of Connect:Direct destination
directory:[/sci/users/jbrown1/cd40]:
Enter full path and name for this support report
file:[/sci/users/jbrown1/cd40/etc/cd.support.rpt]:
ls: /sci/users/jbrown1/cd40/ndm/SACL: Permission denied
cdcustrpt ended

In this example, the user does not have root access, so the Strong Access Control File (sysacl.cfg)
can not be accessed. The following example shows an excerpt from a sample report:

###########################################################################
####### Connect:Direct for UNIX 4.0.00 configuration report #######
###########################################################################
Connect:Direct for UNIX Version 4000, Build 00, IBM/RS6000 AIX, Fix date: 01OCT2007
Install directory: /sci/users/jbrown1/cd40
Local Node name: jb_aix40

Report for: jbrown1

=========================================================
===== Begin: Environment and system information =====
=========================================================

System: AIX skyglass 3 5 00CE208E4C00

Disk usage:
Filesystem 512-blocks Free %Used Iused %Iused Mounted on
/dev/hd4 262144 64216 76% 2479 4% /
/dev/hd2 8126464 2708688 67% 37802 4% /usr
/dev/hd9var 262144 18448 93% 613 2% /var
/dev/hd3 786432 363600 54% 424 1% /tmp
/dev/fwdump 524288 507752 4% 17 1% /var/adm/ras/platform
/dev/hd1 262144 216520 18% 167 1% /localhome
/proc - - - - - /proc
/dev/hd10opt 524288 52168 91% 3688 6% /opt
/dev/fslv00 121634816 13629040 89% 264984 15% /sci
scidalnis01:/export/nis01 1677670392 512499192 70% 0 -1% /home/nis01

Memory statistics:
System Configuration: lcpu=4 mem=3824MB

kthr memory page faults cpu

----- ----------- ------------------------ ------------ -----------
r b avm fre re pi po fr sr cy in sy cs us sy id wa
1 1 400072 232777 0 0 0 0 0 0 4 1805 197 0 1 99 0

Connect:Direct for UNIX User’s Guide 85

Chapter 4 Using Connect:Direct Utilities

Reporting on Connect:Direct Secure+ Option for UNIX

If cdcustrpt detects the Secure+ Option directory in the installation directory,
<installation>/ndm/secure+/, it invokes the Secure+ Option Command Line Utility (splicli.sh) to
report on Secure+ Option parameters. If Secure+ Option is detected, you are prompted to enter the
path to the Secure+ Option parameters file (the default location is provided in brackets “[ ]”), for
example:

Enter full path of Secure+ parmfile

directory: [/sci/users/jbrown1/cd40/ndm/secure+/nodes]:

The following example shows an excerpt from a sample report:

===== Begin: Secure+ parameters =====

=========================================

All secure+ nodes:

**************************************************************
* Secure+ Command Line Interface *
* Connect:Direct for UNIX v4.0.00 *
*------------------------------------------------------------*
* Copyright (c) 1999, 2008 Sterling Commerce Inc. *
* All Rights Reserved. *
**************************************************************

SPCLI> display all;

name=.Local
baserecord=brown_aix38
type=l
protocol=tls
override=n
authtimeout=120
stsenablesig=n
stsenableautoupdate=n
stslimitexportversion=y
stsenableenc=y
stsencalgs=(ideacbc128,tdescbc112,descbc56)
stsauthlocalkey=0305.095A.44E3.BD87.F476.45E8.09B1.FCCA.45ED.67B0.01AD
stsprevauthkeyexpdatetime=
stssiglocalkey=0204.BABA.613D.2FA5.AAE6.0BD4.5847.B610.A17F.C7DD.0AA2
stsprevsigkeyexpdatetime=
ssltlsseaenable=n
seacertvaldef=
ssltlstrustedrootcertfile=/home/nis01/jbrown1/CertificateWizard/cert.crt
ssltlscertfile=/home/nis01/jbrown1/CertificateWizard/athena.selfsigned.keycert.txt
ssltlsenablefipsmode=n
ssltlsenableclientauth=n
ssltlsenablecipher=(TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA)

2007/10/19 14:27:37 parmfile upgraded: SPV4

2007/03/27 09:25:14 jbrown1
2007/03/22 09:54:55 jbrown1

86 Connect:Direct for UNIX User’s Guide

 Generating a Configuration Report

Reporting on Connect:Direct UNIX for SWIFTNet

If cdcustrpt detects the SWIFTNet directory in the installation directory,
<installation>/ndm/SwiftNet/, it includes the contents of the CDSwiftnet.cfg file in the report.
Values for password parameters are replaced by a string of asterisks (*).
The following example shows an excerpt from a sample report:

====================================================================================
Begin: /sci/users/jbrown1/swift31/ndm/SwiftNet/Version3/cfg/CDSwiftnet.cfg
====================================================================================

===== Content of
/sci/users/jbrown1/swift31/ndm/SwiftNet/Version3/cfg/CDSwiftnet.cfg =====
o
# Connect:Direct UNIX for SWIFTNet 3.1.00 configuration file.
#

[Directory.Info]
CD.HomeDir="/sci/users/jbrown1/swift31"
CDSwiftnet.HomeDir="/sci/users/jbrown1/swift31/ndm/SwiftNet/Version3"

# Concatenate the RequestorDN and ResponderDN to these directories for the Request
Handler.
Reception.Dir="/sci/users/jbrown1/reception"
Download.Dir="/sci/users/jbrown1/download"

# This directory must be specified to use the #OLDEST_FILE feature.

Success.Dir="/sci/users/jbrown1/success"

[Log.Info]
#Log.MaxSize="1048576"
Log.MaxSize="35000"
Log.MaxVersions="5"

[connection.info]
# Connection information for Connect:Direct's API port. (Used when forwarding files to
the back office.)
Comm.Info="spyglass;10102"
Userid="jbrown1"
Passwd="********"# this is a test
#ClientInfo="/sci/users/jbrown1/swift31/ndm/SwiftNet/Version3/program/<Encrypted
userid/password file generated by the LCU>"

Connect:Direct for UNIX User’s Guide 87

Chapter 4 Using Connect:Direct Utilities

88 Connect:Direct for UNIX User’s Guide

 Chapter 5

Writing Custom Programs

The Connect:Direct Application Programming Interface (API) allows you to write custom
programs in either C or C++ to use with Connect:Direct. With the C functions or the C++ classes,
you can create programs to perform the following tasks:
✦ Establish a connection to the Connect:Direct server
✦ Disconnect from the server
✦ Receive command responses from the server
✦ Send commands to the server
This chapter describes the format of the Connect:Direct API functions and classes and provides
samples of their use. Sample programs are provided that use the Connect:Direct API functions and
classes to issue commands and receive responses from the Connect:Direct server.

Compiling Custom Programs

After you write a custom program, you must compile it, using a C or C++ compiler. Refer to the
following table to determine what minimum C++ compiler version to use for each platform:

Platform C++ Compiler

AIX IBM XL C++ V8.0 for AIX

Sun Solaris SPARC/x86 C++5.7

HP aCC: HP ANSI C++ B3910B A.03.73

HP-Itanium aCC: HP ANSI C++ B3910B A.06.07

Linux c++ version 3.3.3

Connect:Direct for UNIX User’s Guide 89

Chapter 5 Writing Custom Programs

Use the commands defined in the following table to compile a custom C++ program using the C++
API calls:

Platform C++ Compile Command

AIX

32-bit /usr/vacpp/bin/xlC -qinline -I../include -+ -o sdksample sdksample.C

../lib/ndmapi.a -lbsd -ldl -lsrc -lpthreads

64-bit /usr/vacpp/bin/xlC -q64 -qinline -I../include -+ -o sdksample sdksample.C

../lib/ndmapi64.a -lbsd -ldl -lsrc -lpthreads

Sun

32-bit /opt/SUNWspro/bin/CC -DBSD_COMP -I../include -o sdksample sdksample.C

../lib/ndmapi.a -L/usr/ucblib -L/usr/lib -lsocket -lrpcsoc -lnsl -lelf
-ldl
Note: If /usr/ucblib is not in the LD_LIBRARY_PATH variable, add
-R/usr/ucblib to the compile command.
64-bit /opt/SUNWspro/bin/CC -xarch=generic64 -DBSD_COMP -I../include -o
sdksample sdksample.C ../lib/ndmapi64.a
-L/usr/ucblib/sparcv9 -L/usr/lib/sparcv9
-L/usr/ucblib/amd64 -lsocket -lrpcsoc -lnsl -lelf -ldl
-R/usr/ucblib/sparcv9 -R/usr/ucblib/amd64

HP

32-bit /opt/aCC/bin/aCC -AA -I../include -o sdksample sdksample.C

../lib/ndmapi.a -lrpcsoc -lnsl -ldld -Wl,+s

64-bit /opt/aCC/bin/aCC -AA +DD64 -I../include -o sdksample sdksample.C

../lib/ndmapi64.a -L/usr/lib/pa20_64 -lnsl -ldld -Wl,+s

HP-Itanium

32-bit /opt/aCC/bin/aCC -I../include -o sdksample sdksample.C ../lib/ndmapi.a

-lrpcsoc -lnsl -ldld -Wl,+s -lunwind

64-bit /opt/aCC/bin/aCC +DD64 -I../include -o sdksample sdksample.C

../lib/ndmapi64.a -L/usr/lib/hpux64 -lrpcsvc -lnsl -ldld -Wl,+s
-lunwind

Linux

32-bit g++ -m32 -I../include -O -DLINUX -o sdksample sdksample.C

../lib/ndmapi.a -ldl -lnss_nis /usr/lib/libstdc++.so.5
Note: If you are compiling for Linux z/OS, change -m32 to -m31.

64-bit g++ -I../include -O -DLINUX -o sdksample sdksample.C ../lib/ndmapi64.a

-ldl -lnss_nis /usr/lib64/libstdc++.so.5
Note: A 64-bit Linux OS installation is required to compile 64-bit binaries.

To build a C++ program using the C API calls, such as the apicheck.C sample program, replace the
sdksample.C parameter with the name of the C++ program and rename the output file parameter,
-o sdksample, to the name of the output file you want to create such as apicheck.

90 Connect:Direct for UNIX User’s Guide

 Compiling Custom Programs

Use the commands defined in the following table to compile a C program:

Platform C Compile Command

AIX

32-bit /usr/vacpp/bin/xlc -I../include -+ -o apicheck apicheck.c

../lib/ndmapi.a -lbsd -ldl -lsrc -lC -lpthreads

64-bit /usr/vacpp/bin/xlc -q64 -I../include -+ -o apicheck apicheck.c

../lib/ndmapi64.a -lbsd -ldl -lsrc -lC -lpthreads

Sun

32-bit /opt/SUNWspro/bin/cc -DBSD_COMP -I../include -o apicheck apicheck.c

../lib/ndmapi.a -L/usr/ucblib -L/usr/lib -lCstd -lsocket -lrpcsoc
-lnsl -lelf -ldl -lCrun
Note: If /usr/ucblib is not in the LD_LIBRARY_PATH variable, add
-R/usr/ucblib to the compile command.
64-bit /opt/SUNWspro/bin/cc -xarch=generic64 -DBSD_COMP -I../include -o
apicheck apicheck.c ../lib/ndmapi64.a
-L/usr/ucblib/sparcv9 -L/usr/lib/sparcv9
-L/usr/ucblib/amd64 -lsocket -lCstd -lCrun -lrpcsoc -lnsl -lelf -ldl
-lCrun -R/usr/ucblib/sparcv9 -R/usr/ucblib/amd64

HP

32-bit /opt/ansic/bin/cc -I../include -o apicheck apicheck.c ../lib/ndmapi.a

-lrpcsoc -lnsl -ldld -Wl,+s -lcl -lstd_v2 -lCsup_v2

64-bit /opt/ansic/bin/cc +DD64 -I../include -o apicheck apicheck.c

../lib/ndmapi64.a -L/usr/lib/pa20_64 -lnsl -ldld -Wl,+s -lcl -lstd_v2
-lCsup_v2

HP-Itanium

32-bit /opt/ansic/bin/cc -I../include -o apicheck apicheck.c ../lib/ndmapi.a

-lrpcsoc -lnsl -ldld -Wl,+s -lcl -lstd_v2 -lCsup -lunwind

64-bit /opt/ansic/bin/cc +DD64 -I../include -o apicheck apicheck.c

../lib/ndmapi64.a -L/usr/lib/hpux64 -lrpcsvc -lnsl -ldld -Wl,+s -lcl
-lstd_v2 -lCsup -lunwind

Linux

32-bit gcc -m32 -I../include -O -DLINUX -o apicheck apicheck.c

../lib/ndmapi.a -ldl -lnss_nis /usr/lib/libstdc++.so.5

64-bit gcc -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi64.a

-ldl -lnss_nis /usr/lib64/libstdc++.so.5
Note: A 64-bit Linux OS installation is required to compile 64-bit binaries.

LinuxS390

32-bit gcc -m31 -I../include -O -DLINUX -o apicheck apicheck.c

../lib/ndmapi.a -ldl -lnss_nis /usr/lib/libstdc++.so.5

64-bit gcc -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi64.a

-ldl -lnss_nis /usr/lib64/libstdc++.so.5
Note: A 64-bit Linux OS installation is required to compile 64-bit binaries.

Connect:Direct for UNIX User’s Guide 91

Chapter 5 Writing Custom Programs

Writing Custom C Programs

If you write a custom program using the C API calls, you must include the header file ndmapi.h and
link it with ndmapi.a. A sample program called apicheck.c is provided.
For Java programming, you can call the C API functions by using the JNI and the libndmapi shared
objects: libndmapi.sl for HP and libndmapi.so for the other supported platforms.

Note: Although the JNI is supported, the Connect:Direct Java Application Interface is recommended for
Java programs that invoke the services of Connect:Direct.

Note: The environment variable NDMAPICFG must be set to the pathname of the client configuration
file. Refer to Starting the CLI on page 23 for instructions on setting the environment variable.

Use the following Connect:Direct API functions for C and C++ programs:

C++ Function C Function Description

ndmapi_connect() ndmapi_connect_c() Establishes a connection with the server. Specify the

node to connect to in the ndm_nodespec pointer or in
the CLI/API Configuration Information file. If the call
is successful, NDM_NO_ERROR is returned. Control
returns to the application when the connection is
established and is ready for the first API request.

ndmapi_sendcmd() ndmapi_sendcmd_c() Sends commands to Connect:Direct. You must

provide the command text. The resp_moreflag is a
pointer to the flag indicating that more responses are
pending for the executed command. Invoke
ndmapi_recvresp_c() for C programs or
ndmapi_recvresp() for C++ programs to retrieve the
extra responses. Only the select process and select
statistics commands require the use of
ndmapi_recvresp_c() for use with C and
ndmapi_recvresp() for use with C++.

ndmapi_recvresp() ndmapi_recvresp_c() Receives responses to commands sent to

Connect:Direct. The contents of the response buffer
are returned.

ndmapi_disconnect() ndmapi_disconnect_c() Terminates the API connection.

Three types of Connect:Direct command responses are returned by these functions.

✦ Informational responses return information about the submitted command.
✦ Data responses, stored in the resp_buffer, contain data records.
✦ Error responses return ERROR_H, a pointer to a linked list of all errors found. The ID field
values are fixed for use when debugging. The msgid, feedback, and rc fields are specified by
Connect:Direct and are referred to in message text. The subst field points to a string that
contains substitution variable information to be inserted appropriately in the message text. The

92 Connect:Direct for UNIX User’s Guide

 Writing Custom C Programs

error control structure keeps track of the current and total number of errors. You can move
through the errors by using the next pointer in error entry blocks.
The following code defines the ERROR_H structure:

#define NDM_ERR_ENT_T struct NDM_ERR_ENT_S

#define NDM_ERR_ENT_H NDM_ERR_ENT_T *
#define NDM_ERR_CTL_T struct NDM_ERR_CTL_S
#define ERROR_H NDM_ERR_CTL_T *
struct NDM_ERR_ENT_S
{
int32 id;
char msgid[MSGIDLEN];
int32 feedback;
int32 rc;
char *subst;
NDM_ERR_ENT_H next;
};
struct NDM_ERR_CTL_S
{
int32 id;
int32 cur_entry;
int32 num_entries;
NDM_ERR_ENT_H next;
};

Creating a Connection to Connect:Direct Using ndmapi_connect() or

ndmapi_connect_c()
Use ndmapi_connect() or ndmapi_connect_c() to create a connection to Connect:Direct so that
an application can send commands and receive responses from the commands. Control returns to
the application when the connection is established and Connect:Direct is ready for the first API
request or when an error condition is set.
Following is the format for the ndmapi_connect() or ndmapi_connect_c() function:

int32 ndmapi_connect ERROR_H error, char * ndm_hostname, char * ndm_portname

The following table describes the parameters for the ndmapi_connect() or ndmapi_connect_c()
function:

Parameter Description Value

error A pointer to a Connect:Direct-defined structure that contains error Pointer

information or status information.

ndm_hostname A pointer to the text specification of the Connect:Direct host to Null-terminated

which the connection is made. If this parameter is not specified, string
the host name is determined by first checking the environment
variable TCPHOST. If no value is specified, the tcp.host.name
field in the CLI/API configuration file is checked. If no value is
specified, the gethostbyname() command is invoked and the
default value of ndmhost is used.

Connect:Direct for UNIX User’s Guide 93

Chapter 5 Writing Custom Programs

Parameter Description Value

ndm_portname A pointer to the host port number. If this parameter is not Pointer
specified, the environment variable TCPPORT is checked. If no
value is specified, the value of the tcp.port in the CLI/API
configuration file is checked. If no value is specified, the default
value 1363 is used.

Following are the return codes for the ndmapi_connect() or ndmapi_connect_c() function:

Return Code Description

NDM_NO_ERROR A session was established with the server.

NDM_ERROR A session was not established with the server. Consult the error structure for
detailed error status.

The following sample function illustrates the use of ndmapi_connect() to connect to the sun1 host:

rc=ndmapi_connect (error, "sun1", "3122");

Terminating a Connection Using ndmapi_disconnect() or ndmapi_disconnect_c()

Use ndmapi_disconnect() or ndmapi_disconnect_c() to terminate a connection to Connect:Direct
that was established by a call to ndmapi_connect() or ndmapi_connect_c(). Following is the
format for ndmapi_disconnect() or ndmapi_disconnect_c():

void ndmapi_disconnect

There are no parameters and no return codes for ndmapi_disconnect() or ndmapi_disconnect_c().

Following is a sample ndmapi_disconnect() function:

ndmapi_disconnect ();

Receiving Responses Using ndmapi_recvresp() or ndmapi_recvresp_c()

Use ndmapi_recvresp() or ndmapi_recvresp_c() to receive responses that are associated with a
previous command sent from the application. Following is the format for ndmapi_recvresp() or
ndmapi_recvresp_c():

int32 ndmapi_recvresp ERROR_H error int32 * resp_length, char * resp_buffer, int32 * resp_moreflag

94 Connect:Direct for UNIX User’s Guide

 Writing Custom C Programs

Following are the parameters for ndmapi_recvresp() or ndmapi_recvresp_c():

Parameter Description Value

error A pointer to a Connect:Direct-defined structure Pointer

that contains error information or status
information.

resp_length A pointer to the length, in bytes, of the Pointer to number of bytes returned or
application buffer to receive the response. The 0 if you no longer want to receive
API sets this parameter to the number of bytes responses. Setting this field to zero
returned. purges all queued responses.

resp_buffer A pointer to the application buffer that receives A local buffer, with a size greater than
the command or submit response. This buffer or equal to that set by resp_length and
should allocate 4096 bytes. filled in by ndmapi_recvresp() or
The format of resp_buffer is a free-form text ndmapi_recvresp_c().
record structure. Field names are four The CLI passes the resp_buffer to
characters long and all uppercase. The data AWK for parsing. Valid values include:
can be any length and can include blanks. The ADMN—Connect:Direct administrator
structure is: name
field name=data | field name=data
|... ADPH—Connect:Direct administrator
phone number
For example:
SUBM = username | PNUM = 12 | PNAM CCOD—Completion code
= proc1 |... CKPT—Checkpoint
CLAS—Class
DBYW—Bytes written
DBYX—Bytes received
DCOD—Destination completion code
DDAY—Submit date
DDS1—Destination disposition 1
DDS2—Destination disposition 2
DDS3—Destination disposition 3
DESC—Connect:Direct administrator
description
DFIL—Destination file
DMSG—Destination message ID
DNVL—Destination number of
volumes
DRCW—Records written
DRUX—RUs received
DVOL—Destination volume array
ECMP—Extended compression ON or
OFF

Connect:Direct for UNIX User’s Guide 95

Chapter 5 Writing Custom Programs

Parameter Description Value

resp_buffer FROM—Copy sending node

(cont’d) LCCD—Local completion code
LCLP—Local IP address and port
number
LKFL—Link fail
LMSG—Local message ID
LNOD—Local node
MSGI—Message IDMSGT—Message
text
MSST—Short text
OCCD—Other completion code
OERR—Other node in error
OMSG—Other message ID
PACC—PNODE account
PFIL—Process file
PNAM—Process name
PNOD—PNODE
PNUM—Process number
PPMN—PDS member name
PRTY—Priority
QUEU—Queue
RECC—Record category
RECI—Record ID
RETA—Retain Process
RMTP—Remote IP address and port
number
RSTR—Process restarted
RUSZ—RU Size
SACC—SNODE account
SBID—Submitter node ID
SBND—Submitter node name
SBYR—Bytes read
SBYX—Bytes sent
SCMP—Standard compression
SCOD— Source completion code
SDDY—Schedule date
SDS1—Source disposition 1
SDS2—Source disposition 1
SDS2—Source disposition 2
SDS3—Source disposition 3

96 Connect:Direct for UNIX User’s Guide

 Writing Custom C Programs

Parameter Description Value

resp_buffer SELA—Elapsed time of the event

(cont’d) SFIL—Source file
SMSG—Source message ID
SNAM—Step name
SSTA—Start time of the event
STAR—Start log date/time for record
STAT—Process status
SNOD—SNODE
SNVL—Source number of volumes
SOPT—SYSOPTS record
SRCR—Records read
SRUX—RUs sent
STIM—Schedule time
STOP—Stop time of the event
SUBM—Submitter ID
SUBN—Submitter node
SUMM—Summary output selector
SVOL—Source volume array
TIME—Submit time
XLAT—Translation

resp_moreflag Indicates that more ndmapi_recvresp() or None

ndmapi_recvresp_c() calls must be issued for
more information. This flag occurs only on
select process and select statistics commands.

Following are the return codes for ndmapi_recvresp() or ndmapi_recvresp_c():

Return Code Description

NDM_NO_ERROR The function completed successfully.

NDM_ERROR An error occurred. Consult the error structure for detailed error status.

TRUNCATED Data is truncated because the receiving buffer is too small.

Connect:Direct for UNIX User’s Guide 97

Chapter 5 Writing Custom Programs

Following is a sample ndmapi_recvresp() function:

int32 rc, resp_length;

int32 resp_moreflag;
char resp_buffer[makbuf];

rc= ndmapi_recvresp (error,

&resp_length,
resp_buffer,
&resp_moreflag
);

Sending a Command to Connect:Direct Using ndmapi_sendcmd() or

ndmapi_sendcmd_c()
Use ndmapi_sendcmd() or ndmapi_sendcmd_c() to allow a command to be sent to a
Connect:Direct application. Following is the format of ndmapi_sendcmd() or
ndmapi_sendcmd_c():

int32 rc, resp_moreflag;

struct sendcmd_data ret_data;
rc=ndmapi_sendcmd (error,
"select process pnumber=2,",
&resp_moreflag,
&ret_data
);

Following are the parameters for ndmapi_sendcmd() or ndmapi_sendcmd_c():

Parameter Description Value

error A pointer to a Connect:Direct-defined structure that contains error Pointer

information or status information.

cmd_text A pointer to the null-terminated text string that specifies the Pointer to a text
command to send to Connect:Direct. The command text must be string
followed by a semicolon and terminated with a null.
When you use the submit=filename command from the API,
ensure that you allocate enough storage for the Process text. The
text of the Process submitted is returned in the text string
associated with this parameter when the function completes. If you
do not allocate enough storage for the Process text, a core dump
can result.

resp_moreflag A pointer to the flag that indicates that more responses are pending Pointer to a flag
for the command just executed. Invoke ndmapi_recvresp() or
ndmapi_recvresp_c() to retrieve the extra responses.

98 Connect:Direct for UNIX User’s Guide

 Writing Custom C Programs

Parameter Description Value

ret_data A pointer to a structure containing internal response information for Pointer to a

a command. The structure is: structure
struct sendcmd_data {
char * cmd_name;
ulong cmd_id;
long data1;
long data2;
long data3;
};

sendcmd_data Provides the caller with some information about the user request. Information
Because parsing of command text occurs at the CMGR, the End about the user
User Application (EUA) has no way to identify the command that request
was submitted, unless it generated the text.

cmd_name A pointer to a string with the name of the command submitted. The Pointer to name
CLI uses this pointer to display completion messages. This field of command
enables you to display unique completion messages without any
knowledge of a specific command in the EUA.

cmd_id A four-byte identifier of the command that was found in the Four-byte
command text. Following are the four-byte identifiers: identifier
/**************Command IDs*******************/
#define CHANGE_PROCESS 0x43484750 /* "CHGP" */
#define DELETE_PROCESS 0x44454c50 /* "DELP"*/
#define FLUSH_PROCESS 0x464c5350 /* "FLSP" */
#define SELECT_PROCESS 0x53454c50 /* "SELP"*/
#define SELECT_STATISTICS 0x53454c53 /* "SELS" */
#define SUBMIT 0x5355424d /* "SUBM" */
#define TRACE_API 0x41504920 /* "API " */
#define TRACE_CMGR 0x434d4752 /* "CMGR" */
#define TRACE_SMGR 0x534d4752 /* "SMGR" */
#define TRACE_PMGR 0x504d4752 /* "PMGR" */
#define TRACE_COM 0x434f4d4d /* "COMM"*/
#define TRACE 0x54524143 /* "TRAC" */
#define STOPNDM 0x53544F50 /* "STOP" */

The CLI uses these identifiers to ensure that rules are being
followed. For instance, if an ndmapi_sendcmd returns with the
resp_moreflag set and the cmd_id is not SELECT_STATISTICS or
SELECT_PROCESS, the CLI generates an error.

data1, data2, For future expansion. data1 is used with the submit command to
and data3 return the Process number. data2 is used with the submit command
to return the result of the Process (0, 4, 8, or 16)

Following are the return codes for ndmapi_sendcmd() or ndmapi_sendcmd_c():

Return Code Description

NDM_NO_ERROR or Process Number The function completed successfully.

NDM_ERROR An error occurred. Consult the error structure for detailed

error status.

Connect:Direct for UNIX User’s Guide 99

Chapter 5 Writing Custom Programs

Following is a sample ndmapi_sendcmd() function:

int32 rc, resp_moreflag;

struct sendcmd_data ret_data;
rc=ndmapi_sendcmd (error,
"select process pnumber=2 ;",
&resp_moreflag,
&ret_data
);

Writing Custom C++ Programs

If you write a custom program using C++ API calls, you must include the class called
ConnectDirectSession. The calling program must instantiate ConnectDirectSession and call the
send and receive functions. A sample program called sdksample.C is provided. To write a custom
C++ program, create a ConnectDirectSession class. The class contains the ConnectDirectSession
interface and a constructor and destructor call to allocate and release the storage associated with the
class. This class is the interface to the Connect:Direct methods and provides connection, command,
data retrieval, and error services. Each method returns either CD_SUCCESS or CD_FAILURE.

Note: The environment variable NDMAPICFG must be set to the pathname of the client configuration
file. Refer to Starting the CLI on page 23 for instructions on setting the environment variable.

To use the ConnectDirectSession class, your application must include the cdunxsdk.h header file
provided in the installation and must link with the ndmapi.a file. Following is a sample
ConnectDirectSession class program:

#include "cdunxsdk.h"
#include <iostream.h>
#include <string.h>
void getError(ConnectDirectSession& cdSess);

main()
{
ConnectDirectSession cdSess;
char processText[16384];

if (cdSess.SessionINF->Connect() == CD_SUCCESS)
{
strcpy(processText,"submit maxdelay=unlimited sdksample process snode=SNODENAME
");
strcat(processText,"copy00 copy from (file=sample.txt pnode)");
strcat(processText," to (file=sample.000 snode disp=rpl) ;");

if (cdSess.SessionINF->SendCommand(processText) == CD_SUCCESS)
{
printf("%s completed, pnumber = %ld.\n",
cdSess.SessionINF->GetCommandName(),
cdSess.SessionINF->GetProcessNumber());
sprintf(processText, "SELECT STATISTICS PNUMBER=%ld DETAIL=YES ;",
cdSess.SessionINF->GetProcessNumber());
(cdSess.SessionINF->SendCommand(processText) == CD_SUCCESS)
{

100 Connect:Direct for UNIX User’s Guide

 Writing Custom C++ Programs

}
else
{
getError(cdSess);
}
}
else
{
getError(cdSess);
}
cdSess.SessionINF->DisConnect();
}
else
{
getError(cdSess);
}
}
void getError(ConnectDirectSession& cdSess)
{
if (cdSess.SessionINF->GetFirstError())
{
printf("\nError Message: %s", cdSess.SessionINF->GetMsgID());
printf("\nError Feedback: %d", cdSess.SessionINF->GetFeedBackCode());
printf("\nError RC: %d", cdSess.SessionINF->GetReturnCode());
printf("\nError SUBST: %s\n", cdSess.SessionINF->GetSubstitute()); }

while(cdSess.SessionINF->GetNextError())
{
printf("\nError Message: %s", cdSess.SessionINF->GetMsgID());
printf("\nError Feedback: %d", cdSess.SessionINF->GetFeedBackCode());
printf("\nError RC: %d", cdSess.SessionINF->GetReturnCode());
printf("\nError SUBST: %s\n", cdSess.SessionINF->GetSubstitute());

}
}

The ConnectDirectSession class methods are described in the following table:

Method Description Parameter Return Values

Connect Provides a connection to the void or a CD_SUCCESS or

Connect:Direct server. pointer to an CD_FAILURE
Connect() with a void parameter IP address
connects to the hostname and port and port.
specified in the client configuration file.

DisConnect Disconnects the current session. void CD_SUCCESS or

CD_FAILURE

SendCommand Sends a Connect:Direct command to Pointer to a CD_SUCCESS or

the server for processing. command CD_FAILURE
text buffer.

Connect:Direct for UNIX User’s Guide 101

Chapter 5 Writing Custom Programs

Method Description Parameter Return Values

ReceiveResponse Receives the response from a void CD_SUCCESS or

previously issued command, such as CD_FAILURE
the select statistics command.

GetResponse Retrieves the response from the void Pointer to a response

ReceiveResponse call. buffer.

GetResponseLength Returns the length of the previously void Length of the response
received response buffer. buffer from the
previously issued call.

MoreData Returns a value indicating if void TRUE—If more data is

outstanding data from the previously outstanding.
issued send command call is FALSE—If no data is
available. If the return value is TRUE, outstanding.
call ReceiveResponse again to
retrieve more data.

GetCommandName Returns the command name of the void Pointer to a command

previously issued send command, name buffer.
such as the submit command.

GetProcessNumber Returns the Process number of a void Process number of a

previously issued submit command. submit command.
-1—If no submit
command can be
found.

GetProcessCount Returns the number of Processes void Process number of a

affected by the last send command submit command that
that issued a delete, change, or flush issued a delete,
process. change or flush
process.
-1—If no submit
command can be
found.

GetCurrentError Moves the error data pointer to the void TRUE—If successful
current error in the list. FALSE—If no current
error exists.

GetNextError Moves the error data pointer to the void TRUE—If successful
next error in the list. FALSE—If no more
errors are found.

GetPreviousError Moves the error data pointer to the void TRUE—If successful
previous error in the list. FALSE—If no previous
error exists.

GetFirstError Moves the error data pointer to the first void TRUE—If successful
error in the list. FALSE—If no error is
found.

102 Connect:Direct for UNIX User’s Guide

 Writing Custom C++ Programs

Method Description Parameter Return Values

GetLastError Moves the error data pointer to the last void TRUE—If successful,
error in the list. otherwise FALSE.

GetMsgID Retrieves the message of the current void Return Value: Pointer
error data block. to a message ID if data
You must call one of the block is value.
GetXXXXError methods before calling
this method in order to retrieve the
proper results.

GetFeedBackCode Returns the feedback code of the void Feedback code.

current error data block.

GetReturnCode Returns the Connect Direct return void One of the valid
code. Connect:Direct return
code: 1,4,8,16.

GetStatus Returns the status. void Connect:Direct status

code.

GetSubstitute Returns the current substitution buffer void Pointer to a

associated with the error. substitution buffer.

DisplayError Displays the current error chain to an Parameters: Return Value: Returns
output location. Pointer to a the highest error found
file I/O in the error chain or -1
structure. on error.

Connect:Direct for UNIX User’s Guide 103

Chapter 5 Writing Custom Programs

Following is the ConnectDirectSession class header:

#include <stdio.h>

// Error enumeration.
typedef enum CDErrorCode
{
CD_SUCCESS = 0,
CD_FAILURE = -1

} CDErrorCode;

// <<Interface>>
class CDSession
{
public:
// Communication methods...
virtual CDErrorCode Connect(void) = 0;
virtual CDErrorCode Connect(char *IpAddress, char *IpPort) = 0;
virtual CDErrorCode DisConnect(void) = 0;
virtual CDErrorCode SendCommand(char *CmdText) = 0;
virtual CDErrorCode ReceiveResponse(void) = 0;

// Methods for retrieving ReceiveResponse data...

virtual const char *GetResponse(void) = 0;
virtual int GetResponseLength(void) = 0;
virtual bool MoreData(void) = 0;

// Methods for retrieving SendCommand return data...

virtual const char *GetCommandName(void) = 0;
virtual long GetProcessNumber(void) = 0;
virtual long GetProcessCount(void) = 0;

// Methods to iterate over error collection ...

virtual bool GetCurrentError(void) = 0;
virtual bool GetNextError(void) = 0;
virtual bool GetPreviousError(void) = 0;
virtual bool GetFirstError(void) = 0;
virtual bool GetLastError(void) = 0;

// Methods to retrieve error data...

virtual const char *GetMsgID(void) = 0;
virtual int GetFeedBackCode(void) = 0;
virtual int GetReturnCode(void) = 0;
virtual int GetStatus(void) = 0;
virtual const char *GetSubstitute(void) = 0;

// Method to display error collection...

virtual int DisplayError(FILE *Output) = 0;
};

class ConnectDirectSession
{
public:
// Interface classes
CDSession *SessionINF;

ConnectDirectSession();
~ConnectDirectSession();
};

104 Connect:Direct for UNIX User’s Guide

 Chapter 6

Writing User Exits

The user exit API functions allow you to write custom programs to use with Connect:Direct.

Understanding User Exit Functions

The user exit programs are used by Connect:Direct to invoke user-specific logic at strategic points
within Connect:Direct execution. User exit programs must be C or C++ language programs and
cannot be shell scripts. The PMGR invokes the Statistics user exit program when you start
Connect:Direct and the exit runs as long as Connect:Direct runs. The SMGR invokes the File Open
and Security user exits for each session and stops them when the particular session terminates.

Note: exit_skeleton.c and exit_skeleton.C contain working examples of all three exits and can be
made with the make_exit_c and make_exit_C make files.

The user exit programs are described in the following table:

Program Description

File Open Exit Connect:Direct sends a message to this user exit program to open the source or
destination file during processing of the copy statement. The File Open Exit opens the
source file and identifies the file descriptor. This exit can perform any sort of
processing to file names or directory names. It can also redirect the open request to
other files as needed.
The File Open Exit program (named “exit_skeleton” in this example) must be owned
by root and the setuid bit must be set. Use the following commands:
% chown root exit_skeleton
% chmod u+s exit_skeleton

Security Exit The Security Exit enables you to implement your own security system or provide
access to a third-party security system.

Connect:Direct for UNIX User’s Guide 105

Chapter 6 Writing User Exits

Program Description

Statistics Exit The Statistics Exit is a notification to the user exit program after any record is written
to the statistics file. Whenever a statistics record is written to the statistics file, an
exact copy is passed to this exit.

User Exit Functions

A connection between the user exit and 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 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 Connect:Direct and the
user exit program.

recv_exit_msg() recv_exit_msg_c() Used by both 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 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 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 )

106 Connect:Direct for UNIX User’s Guide

 User Exit Functions

Following is the parameter for the exit_child_init() or exit_child_init_c() function:

Parameter Description Value

logfile The name of the log or trace file that is opened for use by the Name of log file or trace
user exit programs. Because the file open and security exit are file
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.

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

Return Code Description

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

ERROR_RC Communications between 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
Connect:Direct. Control is suspended until a message is received or an error occurs. Following is
the format of recv_exit_msg():

int recv_exit_msg( int exit_flag )

int * msg_type,
char * recv_buf,
int * recv_buf_len

Following are the parameters for recv_exit_msg() or recv_exit_msg_c() functions:

Parameter Description Value

exit_flag A flag to specify the recipient ID. The only valid value a user EXIT_PROGRAM
exit program can use is EXIT_PROGRAM.

msg_type A pointer to the name of the received message. Messages are Pointer to message
requests from Connect:Direct and the associated response
from the user exit program.

Connect:Direct for UNIX User’s Guide 107

Chapter 6 Writing User Exits

Parameter Description Value

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

Following are the return codes for recv_exit_msg()or recv_exit_msg_c(). 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: 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 EXIT_PROGRAM
program can use is EXIT_PROGRAM.

fd The file descriptor of a file that the user exit program opened in the File descriptor
place of Connect:Direct, similar to one returned by the open(2)
function.

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

Return Code Description

GOOD_RC The file descriptor was received successfully.

108 Connect:Direct for UNIX User’s Guide

 User Exit Functions

Return Code Description

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

Send a Message to 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 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
exit program can use is EXIT_PROGRAM.

msg_type A message name. Messages are requests from Pointer to message

Connect:Direct and the associated response from the user
exit program.

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: Connect:Direct terminated or an invalid value is used for the exit_flag or
msg_type parameters.

Connect:Direct for UNIX User’s Guide 109

Chapter 6 Writing User Exits

Understanding User Exit Messages

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 include 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

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

File Open Exit Messages

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.
✦ Do not change the file type specified by the Process. For example, if the Process specifies a
regular file, the user exit cannot open and return a file descriptor for a pipe. No facility is
available to modify contents of the copy control block and return it to Connect:Direct.
✦ If the oflag specifies opening a file with write access and the user exit changes access to
read-only, Connect:Direct will fail when it attempts to write to a read-only file.
✦ The upload and download parameters that restrict directory access are ignored for this user
exit.
For more information about these parameters, refer to the Maintaining Access Information
Files chapter in the Connect:Direct UNIX Administration Guide.

FILE_OPEN_OUTPUT_MSG
During the copy statement process, 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

110 Connect:Direct for UNIX User’s Guide

 Understanding User Exit Messages

✦ UNIX user ID that will own the file

✦ UNIX group ID that will own the file
✦ UNIX user name
✦ A copy of the Connect:Direct copy control block
✦ A copy of the 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 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
Connect:Direct.

FILE_OPEN_INPUT_MSG
During the copy statement Process, 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 Connect:Direct copy control block
✦ A copy of the 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 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)

Connect:Direct for UNIX User’s Guide 111

Chapter 6 Writing User Exits

Security Exit Messages

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, Connect:Direct relies on it for user ID authentication. If the security
exit is not implemented correctly, the security can be compromised.

GENERATE_MSG
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 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
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

112 Connect:Direct for UNIX User’s Guide

 Exit Log Files

✦ 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 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

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

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

Exit Log Files

If user exit programs are specified in the initparm.cfg, Connect:Direct creates exit logs. Exit log
files are provided specifically for the user exit programs and are used for debug and trace type
messages. The user exit program is started with the log file already opened on STDOUT and
STDERR. The exit log files are:
✦ stat_exit.log
✦ file_exit.log
✦ security_exit.log

Note: You can access the log files through the normal printf() and fprintf (stderr,...) functions.

The log files are located in the installed (d_dir) working directory:

.../d_dir/work/cd_node

Connect:Direct for UNIX User’s Guide 113

Chapter 6 Writing User Exits

114 Connect:Direct for UNIX User’s Guide

 Glossary

Application Programming Interface (API)

A library of function calls that enables End User Applications (EUAs) to interact with Connect:Direct.

Client
A program that makes requests of the Connect:Direct server and accepts the server's responses.

Command Line Interface (CLI)

A program available to submit Connect:Direct Processes and commands from a command line
environment.

Command Manager (CMGR)

The program that executes commands sent by the API and sends the results back to the API. In
conjunction with the API, the CMGR carries out the Connect:Direct authentication procedure,
which determines if the user name and password are authorized to access the system. CMGR
interacts with the PMGR when required by command execution.

Connect:Direct
The family of data transfer software products that distributes information and manages production
activities among multiple data centers.

Connect:Direct for UNIX User’s Guide 115

Glossary

Connect:Direct Browser User Interface

As an alternative to submitting Connect:Direct commands through the command line interface, you can use
the Connect:Direct Browser User Interface to create, submit, and monitor Processes from an Internet
browser, such as Microsoft Internet Explorer or Netscape Navigator. You can also use the Connect:Direct
Browser to perform Connect:Direct system administration tasks, such as viewing and changing the network
map or initialization parameters, if you have the appropriate Connect:Direct authority.

Connect:Direct for UNIX

The UNIX implementation of the Connect:Direct product.

Connect:Direct Node
Any computer/workstation running Connect:Direct.

Connect:Direct Process
A series of statements, which can be predefined and stored in a directory, submitted through the API
to initiate Connect:Direct for UNIX activity. Examples of Process functions are copying files
and running jobs.

daemon
The long-running process that provides a service to a client. The PMGR is the Connect:Direct for
UNIX daemon.

Diagnostic Commands
Connect:Direct commands that assist in the diagnosis of Connect:Direct software problems.

End User Application (EUA)

An application program developed by an end user to accomplish a particular task.

Execution Queue
A logical queue in the TCQ. A Process in the Execution Queue can be transferring data to or from
a remote Connect:Direct node or it can be waiting for a connection to the remote
Connect:Direct node before it can perform its tasks.

116 Connect:Direct for UNIX User’s Guide

 Glossary

File Agent
An application program and component of Connect:Direct. It scans specified directories searching
for the presence of a file. When a file appears in a watched directory, Connect:Direct either
submits a Process or performs the action specified by the rules for the file.

Hold Queue
A logical queue in the TCQ. Processes in the Hold Queue are waiting for operator intervention
before they move to the Wait Queue for scheduling.

Monitoring Commands
Connect:Direct commands that allow you to display information from the statistics file and the TCQ
about Connect:Direct Process execution results.

Operational Control Commands

Connect:Direct commands that allow you to submit a Process, change specific characteristics of a
Process in the TCQ, remove executing and nonexecuting Processes from the TCQ, and stop
Connect:Direct.

Process Manager (PMGR)

The long-running Connect:Direct server that initializes the Connect:Direct software, accepts
connection requests from Connect:Direct APIs and remote Connect:Direct nodes, creates
Command Managers and Session Managers, accepts requests from Command Managers and
Session Managers where centralized Connect:Direct functions are required, and terminates
Connect:Direct software execution.

Connect:Direct for UNIX User’s Guide 117

Glossary

PNODE (Primary Node)

The Connect:Direct node on which the Process is being executed. The primary node is also called
the controlling or source node, but is not always the sending node because PNODE can be the
receiver. Every Process has one PNODE and one SNODE. The submitter of a Process is always
the PNODE. The PNODE name can be 1–16 characters long.

Session
A connection between two Connect:Direct nodes.

Session Manager (SMGR)

Responsible for creating or completing a connection with a remote Connect:Direct node and
carrying out the Connect:Direct work to be performed.

SNODE (Secondary Node)

The Connect:Direct node that interacts with the Primary node (PNODE) during Process execution.
The Secondary node (SNODE) also can be referred to as the participating, target, or destination
node. Every Process has one PNODE and one SNODE. The secondary node is the node
participating in Process execution initiated by another node (PNODE). The SNODE name can
be 1–16 characters long.

Sterling Control Center

centralized management system that provides operations personnel with continuous
enterprise-wide business activity monitoring capabilities for Connect:Direct for z/OS,
Connect:Direct for UNIX, and Connect:Direct for Windows servers. It manages multiple
Connect:Direct servers to suspend, release, and delete Processes, stops Connect:Direct servers,
and views detailed statistics on running or completed Processes. It monitors service levels to
view Connect:Direct processing across Connect:Direct z/OS, Connect:Direct for UNIX, and
Connect:Direct for Windows servers within your network and retrieve information about active
and completed Processes. It receives notification of data delivery events that occur or do not
occur as scheduled and defines rules that, based on processing criteria, can generate an alert,
send an E-mail notification, generate a Simple Network Management Protocol (SNMP) trap to
an Enterprise Management System (ESM), or run a system command. It monitors for alerts,
such as a server failure or a Process not starting on time.

118 Connect:Direct for UNIX User’s Guide

 Glossary

TCQ Status Value

A two-letter code assigned to a Process by Connect:Direct when the Process is placed on the TCQ.
The status of a Process can be examined with a select process command.

TCQ (Transmission Control Queue)

A queue that holds all Processes that are submitted to Connect:Direct for UNIX. TCQ contains the
following four logical queues:
™ EXECUTION
™ WAIT
™ TIMER
™ HOLD

Timer Queue
A logical queue in the TCQ. Processes on the Timer Queue are waiting for a start time before they
move to the Wait Queue for scheduling.

Wait Queue
A logical queue in the TCQ. Processes on the Wait Queue are waiting on a connection to or from
the remote Connect:Direct node.

Connect:Direct for UNIX User’s Guide 119

Glossary

120 Connect:Direct for UNIX User’s Guide

 Index

Symbols class parameter

change process command 39
&symbolic name parameter, submit command 35 submit command 30
CLI, description 9
A cmd_id parameter 99
API function calls cmd_name parameter 99
connecting to the Connect:Direct server 92
exit_child_init() 106 cmd_text parameter 98
ndmapi_connect() 93 cmgr parameter 60
ndmapi_disconnect() 94
CMGR, description 8
ndmapi_recvresp() 94
ndmapi_sendcmd() 98 comm parameter 60
overview 89 Command
recv_exit_msg() 107 and the TCQ 63
send_exit_file() 108 change process 14, 27, 37
send_exit_msg() 109 conventions 29
API, description 9 delete process 14, 27, 40
fg 26
C flush process 14, 27, 42
for TCQ 13
C program, compile command 90 foreground 26
operational control 27
C++ program, compile command 90
select process 14, 45, 48
cdcustrpt utility 84 select statistics 14, 52
cdsacomp 76 stop 14, 27, 44
stopping the CLI 27
cfgCheck utility 83 submit 14, 30
arguments 83 syntax 27
change process command trace 14, 59
class parameter 39 Command Line Interface (CLI)
description 27, 37 description 23
format 38 starting 23
hold parameter 39 terminating 27
newsnode parameter 39 using 23
overview 37
pname parameter 38, 42, 45, 48, 52, 53 Command line interface, overview 9
pnumber parameter 38, 42, 46, 48, 53 Command manager, overview 8
prty parameter 40
Commands
release parameter 40
ndmmsg 74
snode parameter 38, 43, 46, 49, 56
ndmxlt 70
submitter parameter 39, 43, 47, 50, 58

Connect:Direct for UNIX User’s Guide 121

 Index

Compile command for a C++ program parameters, -P 24

AIX 90, 91 parameters, -p nnnnn 25
HP 90, 91 parameters, -r 26
Linux 90, 91 parameters, -s 24
LinuxS390 91 parameters, -t nn 25
Sun 90, 91 parameters, -x 25
parameters, -z 26
Compression Utility 76
Configuration Checking Utility
arguments 83 E
Configuration Reporting Utility -e nn parameter, direct command 25
Base installation 84 Error numbers, generated by ndmxlt 73
cdcustrpt 84
error parameter
Secure+ Option 86
ndmapi_connect() function 93
SwiftNet 87
ndmapi_recvresp() function 95
Connect:Direct ndmapi_sendcmd() function 98
API function calls 89
Error responses 92
commands 23
concepts 12 ERROR_RC return code
function calls 89 exit_child_init() function 107
recv_exit_msg() function 108, 109
Connecting to the server, with API function calls 92
Establishing a server connection, using API function 92
Creating translation tables 70
EX status value 66
D Execution queue 65

Data responses, for API commands 92 Exit log files 113

file_exit.log 113
Definition
stat_exit.log 113
local node 12
remote node 12 exit_child_init() function 106
description 106
delete process command 27, 40
parameters, logfile 107
description 40
return codes, ERROR_RC 107
pname parameter 41
return codes, GOOD_RC 107
pnumber parameter 42
snode parameter 42 exit_flag parameter
submitter parameter 42 recv_exit_msg() function 107

Description exit_flag parameter, send_exit_file() function 108

API 9 exit_msg parameter
CLI 9 recv_exit_msg() function 109
CMGR 8
network map 14
PMGR 7 F
TCQ 13 -f parameter, for ndmmsg command 75
user authorization 15
-ffiller parameter 71
destfile parameter, select statistics command 52
File open exit
direct command description 105
parameters, -e nn 25 message types 110
parameters, -h 26
file_exit.log 113
parameters, -n name 25

122 Connect:Direct for UNIX User’s Guide

 Index

filename parameter 30 list, parameter value 29

Files, message 73 Local node
definition of 12
flush process command 27, 42
in network map 14
description 42
logfile parameter
Foreground, moving a CLI process 26
exit_child_init() function 107
Function calls
exit_child_init() 106
ndmapi_connect() 93 M
ndmapi_disconnect() 94 -m parameter 71
ndmapi_recvresp() 94
Managing Processes 63
ndmapi_sendcmd() 98
ndmapi-sendcomd() 98 Manipulating Processes in the TCQ 63
overview 89 max.age, parameter 16
recv_exit_msg() 107
send_exit_file() 108 maxdelay parameter 31
send_exit_msg() 109 Message
files, overview 73
G message ID format 73
message record format 74
Generic parameter value 29
Message utility
GOOD_RC return code message ID format 73
exit_child_init() function 107 message record format 74
recv_exit_msg() function 108, 109 overview 73
Modifying translation tables 70
H Moving a CLI process
-h parameter, for direct 26 foreground 26
HC status value 68 msg_type parameter, recv_exit_msg() function 107
HE status value 68 msg_type parameter, send_exit_msg() function 109
HI status value 68
HO status value 68 N
hold parameter -n name parameter, direct command 25
change process command 39 ndm_hostname parameter 93
submit command 30
NDM_NO_ERROR return code
Hold queue 67 ndmapi_connect() function 94, 97, 99
HR status value 67, 68 ndm_portname parameter 94
HS status value 68 ndmapi_connect() function
description 93
I error parameter 93, 95, 98
format 93
immediate parameter 45 ndm_hostname parameter 93
informational responses, API 92 NDM_NO_ERROR 94, 97, 99
ndm_portname parameter 94

L ndmapi_disconnect() function, description 94

-l parameter, for ndmmsg command 75

Connect:Direct for UNIX User’s Guide 123

 Index

ndmapi_recvresp() function
description 94
P
example 98 -p nnnnn parameter, direct command 25
resp_buffer parameter 95, 96, 97 pacct parameter 31
resp_length parameter 95
resp_moreflag parameter 97 Parameters, scheduling for the TCQ 64
TRUNCATED return code 97 PE status value 66
ndmapi_sendcmd() function 98 pmgr parameter, trace command 61
cmd_id parameter 99
PMGR, description 7
cmd_name parameter 99
cmd_text parameter 98 pname parameter
description 98 change process command 38, 42, 45, 48, 53
resp_moreflag parameter 98 delete process command 41
ret_data parameter 99 pnodeid parameter, submit command 31
sendcmd_data parameter 99
pnumber parameter
ndmmsg change process command 38, 42, 46, 48, 53
description 74 delete process command 42
message ID format 73
message id format 73 Process restart, overview 15
message record format 74 Process statements, listed 12
overview 73
Process, samples 17
parameter, -l 75
parameter, -s 75 prty parameter
parameters, -f 75 change process command 40
using to display message text 73 submit command 31
ndmxlt
creating translation tables 70 Q
errors generated 73
queue parameter 46, 48
modifying translation tables 70
Queues
ndmxlt command parameters
execution 65
-ffiller 71
hold 67
-m 71
timer 67
-ooutputfile 70
wait 66
-rradix 71
-ssourcefile 70 quiesce parameter 45
ndmxlt utility, and the copy statement 72
Network map file
R
description 14 -r parameter, direct command 26
newname parameter, submit command 31 reccat parameter 53
newsnode parameter, change process command 39 recids parameter 54
recv_buf_len parameter 108
O recv_exit_msg() function
-ooutputfile parameter, ndmxlt 70 description 107
ERROR_RC return code 108, 109
Operational control commands 27
exit_flag parameter 107, 108, 109
GOOD_RC return code 108, 109
msg_type parameter 107, 109

124 Connect:Direct for UNIX User’s Guide

 Index

recv_buf_len parameter 108 select statistics command 52

send_buf parameter 108 description 52
format 52
release parameter 40
reccat parameter 53
Remote node recids parameter 54
definition of 12 required parameters 52
in network map 14 startt parameter 57
Remote node information record stopt parameter 57
creating 19 send_buf parameter
resp_buffer parameter 95, 96, 97 recv_exit_msg() function 108
send_exit_msg() function 109
resp_length parameter 95
send_buf_len parameter 109
resp_moreflag parameter
ndmapi_recvresp() function 97 send_exit_file() function
ndmapi_sendcmd() function 98 description 108
format 108
ret_data parameter 99
send_exit_msg() function 109
retain parameter 32 description 109
Return codes format 109
ERROR_RC, exit_child_init() function 107 send_buf parameter 109
ERROR_RC, recv_exit_msg() function 108, 109 send_buf_len parameter 109
GOOD_RC, exit_child_init() function 107 sendcmd_data parameter 99
GOOD_RC, recv_exit_msg() function 108, 109
NDM_NO_ERROR, ndmapi_connect() Session manager
function 94, 97, 99 description 8
TRUNCATED, ndmapi_recvresp() function 97 overview 8
-rradix parameter, for ndmxlt utlity 71 Shell script, samples 17
SMGR 8
S trace command 61

-s parameter snode parameter

direct command 24 change process command 38, 43, 46, 49, 56
ndmmsg command 75 delete process command 42
select process command 47, 50
sacct parameter 32 submit command 33
Samples snodeid parameter 34
Processes 17
shell scripts 17 srcfile parameter
select statistics command 57
Scheduling Connect:Direct activity 64
retain parameter 64 -ssourcefile parameter 70
startt parameter 64 Standalone Batch Compression 76
Security exit startt parameter
description 105 select statistics command 57
message types 112 submit command 35
select process command 45, 48 stat_exit.log 113
description 45, 48
statistics exit
queue parameter 46, 48
description 106
snode parameter 47, 50
message types 110

Connect:Direct for UNIX User’s Guide 125

 Index

Status values TCQ, description 13

hold queue 68
Timer queue 67
overview 64
wait queue 66 trace command 59
cmgr parameter 60
step parameter 45
comm parameter 60
Sterling Control Center 10 description 59
format 59
stop command 27, 44
pmgr parameter 61
description 44
smgr parameter 61
immediate parameter 45
quiesce parameter 45 Translation table utility
step parameter 45 and the copy statement 72
creating translation tables 70
Stopping the CLI 27
error numbers 73
stopt parameter 57 modifying translation tables 70
submit command Transmission Control Queue
&symbolic name parameter 35 and commands 63
class 30 hold parameter 64
description 30 overview 63
filename parameter 30 status values in hold queue 68
hold 30
Transmission Control Queue, process progression 65
newname parameter 31
parameter, maxdelay 31 TRUNCATED return code 97
parameter, prty 31
parameters, pacct 31
pnodeid parameter 31
U
retain parameter 32 User authorization information file, description 15
sacct parameter 32 User exits
snode parameter 33 file open exit 105
snodeid parameter 34 file open exit message type 110
startt parameters 35 security exit 105
submitter parameter security exit types 112
change process command 39, 43, 47, 50, 58 statistics exit 106
delete process command 42 statistics exit messsage 110
Submitting a Process, defined 27 Utilities
ndmxlt and the copy statement 72
T ndmxlt, creating translation tables 70
ndmxlt, modifying translation tables 70
-t nn parameter, direct command 25 translation table 70
translation table and the copy statement 72
TCQ
translation table, modifying translation tables 70
and commands 63
hold parameter 64
overview 63 V
Process progression 65
Validating configuration files 83
retain parameter 64
startt parameter 64 view process, command 27, 45
TCQ status values
hold queue 68
wait queue 66

126 Connect:Direct for UNIX User’s Guide

 Index

W
WA status value 66
Wait queue 66
WC status value 66, 67
Wildcard facility 29
WR status value
timer queue 67
wait queue 66
WS status value 66, 67

X
-x parameter, direct command 25
XXLT001I error number, translation table 73
XXLT002I error number, translation table 73
XXLT003I error number, translation table 73
XXLT004I error number, translation table 73
XXLT005I error number, translation table 73
XXLT006I error number, translation table 73
XXLT007I error number, translation table 73
XXLT008I error number, translation table 73

Z
-z parameter, direct 26

Connect:Direct for UNIX User’s Guide 127

 Index

128 Connect:Direct for UNIX User’s Guide