IBM Sterling Connect:Direct for Microsoft

Windows

SDK Programmers Guide

Version 4.6
Contents

Overview.....................................................................................................................................................4
Sterling Connect:Direct for Microsoft Windows SDK Overview.............................................................................................4

Edit Connection Settings...........................................................................................................................6

Edit Connection Settings with the Client Connection Utility...................................................................................................6
Start the Client Connection Utility............................................................................................................................................7
Add and Delete Node Connection Definitions..........................................................................................................................7
Add a Node................................................................................................................................................................................7
Delete a Node............................................................................................................................................................................8
Add a User.................................................................................................................................................................................9
Delete a User.............................................................................................................................................................................9
Update Node Properties...........................................................................................................................................................10
Define a Default Node or Default User...................................................................................................................................10
Import Registry Settings..........................................................................................................................................................11
Export Registry Settings..........................................................................................................................................................11
Print Registry Settings Report.................................................................................................................................................11

Apply the C API.......................................................................................................................................13

The C Applications Programming Interface............................................................................................................................13
Compile and Debug.................................................................................................................................................................13
Activate Tracing.......................................................................................................................................................................13
Standard C API........................................................................................................................................................................14
View Sample Programs...........................................................................................................................................................15

Apply the C++ Class Interface................................................................................................................16

Compile and Debug.................................................................................................................................................................16
Manipulate Nodes....................................................................................................................................................................16
Create an Object to Connect to a Node...................................................................................................................................17
Manage Connections...............................................................................................................................................................18
View Information.....................................................................................................................................................................18
Control the Return of Information...........................................................................................................................................19
Execute Sterling Connect:Direct Commands..........................................................................................................................20
Manage Exception Conditions................................................................................................................................................22
Manage Administrative Functions...........................................................................................................................................22
Multithreaded Access and Blocking........................................................................................................................................24
Objects On The Stack..............................................................................................................................................................24

Apply the ActiveX Control Interface......................................................................................................26

Submit Process........................................................................................................................................................................26
Display Select Statistics Results..............................................................................................................................................27

Apply Automation Servers......................................................................................................................33

Apply Automation Servers......................................................................................................................................................33
Create Virtual Servers Using the Node Factory.......................................................................................................................33
Use Automation Objects..........................................................................................................................................................36

Enhance Security and Automate File Opening with User Exits..........................................................39

2 SDK Programmers Guide

 Contents

User Exits................................................................................................................................................................................39
Apply Enhanced Security........................................................................................................................................................39
Apply Automated File Opening...............................................................................................................................................41

Structure Types........................................................................................................................................43
Structure Types........................................................................................................................................................................43
NETMAP_DESC_STRUCT Structure....................................................................................................................................43
USER_STRUCT Structure......................................................................................................................................................44
MESSAGE_STRUCT Structure..............................................................................................................................................46
NETMAP_MODE_SNA Structure.........................................................................................................................................46
NETMAP_MODE_TCP Structure..........................................................................................................................................47
NETMAP_NODE_STRUCT Structure...................................................................................................................................47
NETMAP_PATH_STRUCT Structure....................................................................................................................................49
PROCESS_STRUCT Structure...............................................................................................................................................50
NODE_STRUCT Structure.....................................................................................................................................................52
STATISTICS_STRUCT Structure...........................................................................................................................................53
TRACE_STRUCT Structure...................................................................................................................................................54
TRANSLATE_STRUCT Structure.........................................................................................................................................55

Return Codes............................................................................................................................................57
C++ Class and the C API Functions Return Codes.................................................................................................................57

Notices.......................................................................................................................................................59
Notices.....................................................................................................................................................................................59

© Copyright IBM Corp. 2011 3

 Overview

Sterling Connect:Direct for Microsoft Windows SDK Overview

Use the IBM® Sterling Connect:Direct®for Microsoft Windows Software Development Kit (SDK) to extend
an application to include the automated file transfer capabilities of Sterling Connect:Direct for Microsoft
Windows. SDK uses a 32-bit interface for C and C++ as well as an OLE automation server for Visual Basic
applications. SDK also provides ActiveX controls for Submit Process and Select Statistics commands.
• C API functions—Standard and registry API functions. The standard functions allow you to connect to a
Sterling Connect:Direct node, execute Sterling Connect:Direct commands, manage command response data,
and retrieve error information. The Registry API functions store and retrieve client connection information
to and from the Registry. The C API is implemented using the C++ Classes.
• C++ Class interface—Provides the foundation for the other Sterling Connect:Direct interfaces and provides
Visual C++ programmers an object-oriented interface to Sterling Connect:Direct.
• ActiveX control interface—Uses the CDSubmit and CDStatistics functions to submit Processes to the server
and display statistics from the statistics database.
• Direct Automation Servers—Provides an automation wrapper around the Sterling Connect:Direct SDK C++
classes. They provide direct automation support for languages like Visual Basic. The Sterling Connect:Direct
Automation Servers provide the following primary classes that map directly to the CDNode, CDProcess, and
CDStatistics classes in the SDK C++ classes:
• User exits—Provides a way to customize Sterling Connect:Direct operations. User exits are user-defined
dynamic link libraries (DLLs) that are loaded and called when the user exit is enabled through an initialization
parameter. Two user exits are provided: one for enhanced security and one for automated file opening.
Before you can use the SDK tools, you can run the Client Connection Utility to configure server access
information, such as TCP/IP information. Alternatively, you can let your SDK application specify the access
information. Some SDK languages also support the Logon Configuration Utility (LCU files).

Distribute an Application
The following SDK files are required to be included when distributing an application developed with this SDK.
• For C++ applications:
• CdCore.dll
• For C applications:

4 SDK Programmers Guide

 • CdCore.dll
• CdCapi.dll ("C" wrapper for cdcore.dll)
• For VB - Automation Server
• CdCore.dll
• CDAuto.dll
• CdAuto.tbl
• For VB - Active X
• CdCore.dll
• CDStats.ocx
• CDSubmit.ocx

DLL files are loaded by using the following algorithm:

1. The directory containing the .exe that is loading the .dll
2. The current directory
3. The system directory (system32)
4. The Microsoft Windows directory
5. The directories list in the PATH environment variable.
Also, the OCX files must registered in the following manner:
• regsvr32 "C:\Program Files\Sterling Commerce\CONNECT Direct v4.6.00\SDK\CDSubmit.ocx"
• regsvr32 "C:\Program Files\Sterling Commerce\CONNECT Direct v4.6.00\SDK\CDStats.ocx"
Or you may use the "/s" option to do so without bringing up a dialog box:
• regsvr32 /s "C:\Program Files\Sterling Commerce\CONNECT Direct v4.6.00\SDK\CDSubmit.ocx"
• regsvr32 /s "C:\Program Files\Sterling Commerce\CONNECT Direct v4.6.00\SDK\CDStats.ocx"
In addition, when using the automation server, you also need to register CDAuto.dll. For example:
regsvr32 "C:\Program Files\Sterling Commerce\CONNECT Direct v4.6.00\SDK\CDAuto.dll"

If you are using the automation server, you must also register your Type Library files (.TLB) using regtlib.exe.
Regtlib.exe is distributed with Visual Studio 6 and above and has updates available in the service packs or in
other Microsoft Windows Library updates.

Note: CDCoreD.dll and CDCapiD.dll are debug versions and do not need to be be distributed with the
application.
Applications may also require the Microsoft Visual Studio Redistributable Runtimes. Not every system has
this installed by default.
For checking about required DLLs, Microsoft's Dependency Walker (depends.exe) is the tool to use. It lists
in detail all DLLs required by an application. The tool is included in the Resource Kit, Microsoft Windows
2000 Support Tools, Visual Studio and other packages.

© Copyright IBM Corp. 2011 5

 Edit Connection Settings

Edit Connection Settings with the Client Connection Utility

To use the SDK to create your own programs, you must create connection settings for each user.
Two methods are available to create local node definitions. You can use either IBM Sterling Connect:Direct
Requester or the Client Connection Utility. If you want to use Sterling Connect:Direct Requester, refer to the
IBM Sterling Connect:Direct for Microsoft Windows System Guide for instructions.
The Sterling Connect:Direct for Microsoft Windows client software uses the Microsoft Windows Registry to
store its configuration information. The Sterling Connect:Direct Client Connection Utility allows you to update
the connection settings within the Registry.

Caution: Use the Sterling Connect:Direct Client Connection Utility to update Registry settings for Sterling
Connect:Direct API connections, rather than editing them directly.
You can view, edit, and update Sterling Connect:Direct for Microsoft Windows connection settings in the
Windows Registry with the Client Connection Utility. The connection settings enable communication between
the user interfaces and the Sterling Connect:Direct server. You can set up and update connection settings by:
• Adding a node
• Deleting a node
• Adding a user
• Deleting a user
• Updating node properties
• Defining a default node or user
To facilitate updating connection settings on multiple servers, you can import and export connection settings
using the Client Connection Utility. After you configure the connection for a server, you can export the server’s
settings for use on other servers. You can then import the settings into the target server’s Registry. You can
also print connection settings.

6 SDK Programmers Guide

Start the Client Connection Utility
To start the Client Connection Utility:
1. Click Start > All Programs.
2. Click IBM Sterling Connect Direct V4.6.00.
3. Select CD Client Connection Utility. The Client Connection Utility main window is displayed.

Add and Delete Node Connection Definitions

Use the Client Connection Utility to add new nodes, look at node properties, and delete existing nodes.
The Sterling Connect:Direct Client Connection Utility enables you to add new nodes and identify their properties,
such as node name, TCP/IP address, and port number. These properties establish a node so you can access it
from Sterling Connect:Direct Requester or the Command Line Interface (CLI).
You can also use the Client Connection Utility to delete existing nodes.

Add a Node
To add a Sterling Connect:Direct node:
1. Select File > New Node. The Node Properties dialog box displays:

© Copyright IBM Corp. 2011 7

 2. To add a node that is registered in the Active Directory:
a) In Operating System, select Windows.
b) Select the node to add from Active Directory Nodes.
The name, address, and port fields are automatically updated with information from the Active Directory
list.
3. To add a node that is not registered in the Active Directory:
a) In the Name field, type the name of the Sterling Connect:Direct node you want to add.
b) If necessary, change the value in Operating System.
c) In Address, type the TCP/IP address of the new node.
d) The Port field automatically defaults to 1363; if necessary, type in a different port number.
4. To specify the new node as the default node, click Set as the Default Node.
5. Click OK to save your settings and close Node Properties.
6. Select File > Save to save the new settings.

Note: Changes made to node settings are not written to the Registry until you select Save.

Delete a Node
To delete a Sterling Connect:Direct node:
1. In the Client Connection Utility main window, select the node you want to delete.
2. Select Edit > Delete.
3. Click Yes to confirm the deletion.
4. Select File > Save to delete the node.

Note: Changes made to the node settings are not written to the Registry until you select Save.
The node is no longer displayed in the Client Connection Utility window.

8 SDK Programmers Guide

Add a User
To add a new Sterling Connect:Direct user:
1. In the Client Connection Utility main window, select the node where you want to add a new user.
2. Select File > New User to display the User Properties dialog box.

3. Type information into the following fields:

• Name—type the name of the new user. Either type the user name as defined in the Microsoft Windows
setup, such as lmore, or type a fully qualified user name in the UPN format, such as
lmore@adtree.stercomm.com
• Password— type the password defined for the user.
• Verify Password—retype the password defined for the user.
4. Click Remember Password to automatically reload the password when you attach as this user.
5. Click Set as the Default User if you want the new user to be the default user for the node.
6. Click OK to save the settings and close User Properties.
7. If the verification password you typed does not match the initial password, you receive a message indicating
that the passwords do not match. Retype the verification password and click OK.
8. Select File > Save to save the settings.

Note: Changes made to node settings are not written to the Registry until you select Save.

Delete a User
1. If the user names are not displayed, click the plus (+) sign next to the node containing the user you want
to delete.
2. Select the user you want to delete.
3. Select Edit > Delete.
4. Click Yes to confirm the deletion.

© Copyright IBM Corp. 2011 9

 5. Select File > Save to save the new configuration.

Note: Changes made to node settings are not written to the Registry until you select Save.

Update Node Properties

To update node and user properties:
1. Do one of the following:
• To update a node, highlight the node you want to configure.
• To update user properties, highlight the user you want to configure.
2. Select File > Properties.

3. Make the appropriate changes.

4. Click OK to save your settings and return to Node Properties.
5. Select File > Save to save the settings.

Note: Changes made to node settings are not written to the Registry until you select Save.

Define a Default Node or Default User

To define a default node or default user:
1. Take one of the following actions:
• To define a default node, highlight the node.
• To define a default user, highlight the user.
2. Select Options > Set as Default to set the default node or user.

10 SDK Programmers Guide

 3. Select File > Save to save the settings. The default node or user is displayed in the main Client Connection
Utility window as bold text.

Note: Changes made to node settings are not written to the Registry until you select Save.

Import Registry Settings

To import registry settings from a file:
1. Select the node in which to import the Registry settings.
2. Select File > Import. A message displays informing you that all settings will be lost.
3. Click Yes. The Open dialog box displays.

Note: Importing a Registry settings file causes all current changes to the selected node to be lost if they
have not been saved.

4. Select the Registry settings file you want to import (.REX extension) and click OK. The imported Registry
settings are applied to the node you selected.
5. Select File > Save to save the settings.

Note: Changes made to node settings are not written to the Registry until you select Save.

Export Registry Settings

To export Registry settings to a file:
1. From the Client Connection Utility main window, select the node containing the Registry settings you want
to export.
2. Click File > Export.
3. Name the exported Registry file with a REX extension and click OK. The Registry settings in the file can
now be imported into another computer or node.

Print Registry Settings Report

To generate and print the registry settings report:
1. To preview the Registry settings report before printing it:
a) Select File > Print Preview.
b) Click Zoom In to enlarge the text and read the report.
2. To print the report:
a) Select File > Print.
b) If necessary, select a printer.

© Copyright IBM Corp. 2011 11

 c) Click OK. A report of all Registry settings is generated.

Note: Additional node detail is provided if the node has been used at least once by the client software.

12 SDK Programmers Guide

 Apply the C API

The C Applications Programming Interface

The Sterling Connect:Direct C applications programming interface consists of Standard and Registry API
functions. The Standard API functions connect to a Sterling Connect:Direct node, execute Sterling
Connect:Direct commands, manage command response data, and retrieve error information. The Registry API
functions store and retrieve client connection information to and from the Registry. The C API is implemented
using the C++ Classes. This interface is used by C programmers.

Compile and Debug

When you are ready to compile the program created with the API, include the CDCAPI.H header file. Including
the CDCAPI.H file in your project automatically links a program with the appropriate import library. Debug
configurations link with the CDCAPID.LIB and release configurations link with the CDCAPI.LIB.
The CDCAPI.LIB and CDCAPID.LIB files contain the following information:
• Name of the DLL to dynamically load at run time.
• Definitions of all exported functions. This is used by the linker to resolve all calls to the CDCAPI.DLL.
When the program runs or the DLL is loaded, the appropriate CDCAPI.DLL is loaded. The CDCAPI.DLL is
dynamically loaded when a release configuration is executed, and the CDCAPID.DLL is dynamically loaded
to support debug configurations.
The C APIs are based on the core C++ APIs. This required API layer is contained in CDCORE.DLL (or
CDCORED.DLL if compiling for debug mode). The appropriate core DLL must be in your path for the C
APIs to work properly.

Activate Tracing
The Output window of the Microsoft Visual Studio displays trace messages.
The following table describes the tracing parameters. Use the trace parameters to activate tracing.

© Copyright IBM Corp. 2011 13

 Parameter Description
CdGetTraceFlags(unsigned int* pgrfTrace); Retrieves the current trace settings for the Sterling Connect:Direct API.
CdSetTraceFlags(unsigned int grfTrace); Sets new trace settings for the Sterling Connect:Direct API.
CdSetTraceFile(LPCTSTR pszFilename); Provides a file name to the tracing facility. If a file is defined, trace messages
are written to the Output window and specified file.

Standard C API

Overview
Use the Standard API functions to connect to a Sterling Connect:Direct node, execute Sterling Connect:Direct
commands, manage command response data, and retrieve error information.
The C API is implemented using the C++ Classes. This interface is used by C programmers.

Handles
Handles simplify object and memory management by referencing a particular object. Pass a handle to an API
to uniquely identify an object. The Sterling Connect:Direct C API uses the following types of object handles
to return node, Process, statistics, message, and trace information:
• Node Handles—Represent the Sterling Connect:Direct node that is the target of the operation. It is a virtual
connection to a Sterling Connect:Direct node. The node handle is a special type of object handle; it holds
information about the node but does not return data from the node.
A node handle is created by calling the CdConnect() function and passing it the node name, user ID, password,
and protocol within a NODE_STRUCT structure. After you finish with a node handle, you call the
CdCloseHandle() to close it. Closing the handle releases the virtual connection and any internal resources
associated with it. The node handle is no longer valid on subsequent operations.

Note: You are responsible for closing the node handle and for releasing any resources that you allocate.
• Process Handles—Handles returned from a submit command or from a Process object, which is created when
a select process, change process, or delete process command is executed. The following example demonstrates
the select process command returning a Process:
if (CdExecuteCommand (hNode, “SELECT PROCESS”, &hProc))
{
if (CdGetProcRec(hProc, &Proc))
{
printf("%d %s/n", Proc.ProcessNumber, Proc.ProcessName);
}
}

• Statistic Handles—Statistics objects that are returned after a select statistics command is executed.
• Message Handles—Message objects that are returned when a select message command is executed.
• Trace Handles—Trace objects that are returned when a traceon or traceoff command is executed.

Block the Calling Thread

CdWaitOnProcess()—Use this function to serialize Sterling Connect:Direct Process execution. This function
blocks the calling thread until the specified Process is no longer in the TCQ. It takes a Process handle that

14 SDK Programmers Guide

 contains references to the target Process object. Any Process object handle can enable you to specify Processes
to wait on. Use this method to wait on a Process returned from a submit command and any Process returned
by the select process command.

Retrieve Error Text

• CdGetErrorText()—Call this function to translate return code values into messages that explain the error.
This helps the user understand the error message and provides a method for logging meaningful trace messages
within an application.
• CdGetDetailedError()—Use this function to retrieve messages one at a time until CD_ENDOFDATA is
returned. This call fills in the MESSAGE_STRUCT structure with a detailed error message for node, parser,
and connection errors. The messages are erased upon entry to any other API to prepare for other potential
errors.

Blocking
The C Application Programming Interface is synchronous; when an API that performs a complex function
(such as the CdConnect() or CdExecuteCmd() functions) is called, the caller’s thread is blocked until the
request is completed or until a failure occurs. The caller’s thread blocks while waiting for other threads to
finish the request.
If the CdConnect() function is called from a Microsoft Windows application, it should not be called from the
primary user interface (UI) thread. Calling the function from the UI thread causes the user interface of the
program to run slowly.

View Sample Programs

Sample programs are available for viewing.
Refer to the documentation CD directory, CDSDK\Samples for the C, C++, and Visual Basic sample code.
The sample code contains the following:
• The CSample1.C sample program demonstrates how to connect to a node, execute a command, and view the
data returned by the node.
• The CSample2.C sample program demonstrates a more complex transaction of connecting to a node, submitting
a Process, waiting for completion, and requesting statistics for the Process.
• CPPSamp1
• CPPSamp2
• VBAuto
• VBStat
• VBSubmit
• VBSubmit2

© Copyright IBM Corp. 2011 15

 Apply the C++ Class Interface

Compile and Debug

Include the CDSDK.H header file to use the C++ interface. CDSDK.H automatically links the program with
the appropriate import library. Debug configurations link with the CDCORED.LIB, and the release configurations
link with the CDCORE.LIB.

Note: You do not need to add the LIB to the LINK section of the project or makefile.
The CDCORED.lib and CDCORE.lib files contain the name of the DLL to dynamically load at run time and
class definitions for the linker to resolve the Sterling Connect:Direct SDK symbols included in the CDSDK.H
file. When a program executes or a DLL is loaded, the appropriate CDCORE.DLL is loaded. Applying.DLL
is dynamically loaded when a debug configuration is executed and to support a release configuration.

Manipulate Nodes
Component Group classes provide methods to make changes on a Sterling Connect:Direct node.
The Component Group classes represent Sterling Connect:Direct entities and provide methods to manipulate
an object to generate changes on the Sterling Connect:Direct node. Use the following classes to manipulate
nodes:
Class Description
CDNode Contains the high-level Sterling Connect:Direct functionality. It returns network map,
initialization parameters, and translation table information as well as User and Proxy
objects that maintain node information and execute command objects.
CDUser Contains the user functional authority information. Use to add, delete, and update
functional authorities on the Sterling Connect:Direct node, including Network map
Access Flags, Command Access Flags, Control Flags, Process Statement Flags,
and default directories.
CDProxy Contains the Sterling Connect:Direct proxy information. Use to add, delete, and
update proxy information on the Sterling Connect:Direct node. The remote user
proxy contains information for operations initiated from a remote Sterling

16 SDK Programmers Guide

 Class Description
Connect:Direct node and defines relationships between a remote node and local
user IDs.
CDTranslationTable Contains and maintains the translation table information that translates data being
sent to other nodes and provides methods for setting and retrieving translation
information.
CDTrace Holds the trace criteria. It contains all the fields returned from the node with the
TRACEON command, with no parameters and provides access methods for all of
the Trace fields.
CDNetmapNode Contains the network map node information.
CDNetmapDesc Contains the description for a network map node.
CDNetmapPath Contains the network map path information.
CDNetmapMode Contains the network map mode information.

When using the C++ Class interface, no sequence must be followed when using the C++ classes. All objects
are self-contained and are not dependent on any other classes when fully constructed. Each object’s constructor
is different and some of the objects require another object to be built successfully.
The first and most important class is the CDNode class. This class is the first one to use when interacting with
any Sterling Connect:Direct node.
While the only prerequisite for constructing a class is the creation of the objects needed by the constructor,
the following example shows a possible sample execution sequence:
CDNode creation
CDSelectProcCommand creation
CDProcIterator creation
(Use the data)
CDProcIterator destruction
CDSelectProcCommand destruction
CDNode destruction

The Sterling Connect:Direct CDNode class serves as the virtual Sterling Connect:Direct node. It enables you
to manipulate and send commands to the actual Sterling Connect:Direct node. You manipulate this object
through the use of the CDNode methods and issue commands to the node using Command objects. Calling
these methods and using the objects sends KQV streams to the physical Sterling Connect:Direct node. See the
C++ API Reference Guide for more information.

Create an Object to Connect to a Node

The name of the Sterling Connect:Direct node and the connection information is set at object creation time
using the CDNode constructor. If a parameter is not supplied (NULL pointer), the default value for that
parameter is read from the Registry. During construction, the CDNode object attempts to connect to the physical
Sterling Connect:Direct node using the protocol information contained in the Registry. If the connection fails,
the CDConnectionException is returned. If the connection is successful but the logon is denied by the server,
a CDLogonException is returned.

© Copyright IBM Corp. 2011 17

 The CDNode object creates and removes the connection to the Sterling Connect:Direct node as needed.
Connections are shared and reused as different requests are made. The following section of the class definition
displays the methods to construct a CDNode object and methods to retrieve node information:
// Constructor for CDNode
CDNode(LPCTSTR szName=NULL, LPCTSTR szUserid=NULL, LPCTSTR szPassword=NULL,
int nProtocol=CD_PROTOCOL_TCPIP);
CDNode(LPCTSTR szFilename);
CDNode(const CDNode &Node);
~CDNode();
//Node Information Methods
const CString GetName() const;
LPCTSTR GetCDName() const;
LPCTSTR GetUserid() const;
LPCTSTR GetServer() const;
int GetProtocol();

The following two examples illustrate two different methods for creating a CDNode object. The first method
creates the CDNode object locally on the stack. The second example creates a dynamic allocation of a CDNode
object from the stack. Both methods then execute a SELECT PROCESS command using the CDNode object.
{
CDNode MyNode("MYNODE", "MYUSERID", "MYPASSWORD");
CDSelectProcCmd cmd;
//Execute the "SELECT PROCESS" command
CDProcIterator it = cmd.Execute(MyNode);
}
{
CDNode *pNode = new CDNode("MYNODE", "MYUSERID", "MYPASSWORD");
CDSelectProcCmd cmd;
//Execute the "SELECT PROCESS" command
CDProcIterator it = cmd.Execute(pNode);
delete pNode;
}

Manage Connections
Use the CDNode class to manage Sterling Connect:Direct connections. The CDNode class creates and deletes
connections to the Sterling Connect:Direct node as needed and deletes the connections if they are idle for a
specified period of time.
The connections are stored in an array and are created and assigned by the CDNode object when a command
requests a connection to the physical node. Connections are reused when they are idle and are deleted if they
remain idle for an extended period of time. Because each connection consumes resources on both the client
and the server, use them as efficiently as possible. The DisconnectAll member function is used to disconnect
all connections to all nodes.

View Information
Record Group classes allow you to view information about processes, statisitics, messages, and users.

18 SDK Programmers Guide

 Use the following classes to obtain information:
Class Description
CDProcess
Contains all of the Process criteria information returned from a SUBMIT or SELECT PROCESS
command after a Process is submitted. You can submit a Process for execution using one of the
following methods:
Create a CDSubmitCmd object and initialize the parameters. Next, call the CDSubmitCmd::Execute()
method and specify the CDNode object to run on. Call the CDNode::Submit() method and specify the
text of the Process. This method internally creates the CDSubmitCmd object and calls the Execute()
method.

CDStatistic
Provides two methods for holding statistics information.
GetAuditField() Method—Because audit data is optional, and different records have different KQV
keys, use a single method to access the data. To retrieve a value, call GetAuditField(), passing the
KQV key for the desired field.
The GetAuditMap() function retrieves all audit fields defined in the current record. An MFC
CMapStringToString object maps from KQV keywords to the corresponding values. This method
enables you to view each association in the map to determine what audit fields are available and to
ask the map for the value of the given field.

CDMessage Holds information about a specific message that is retrieved from the Sterling Connect:Direct node
CDUser Holds the user functional authority information to add, delete, and update functional authority information
on the Sterling Connect:Direct node.

Control the Return of Information

Use iterators to enumerate through multiple returned objects.
Commands and methods store multiple items in an iterator. The iterator provides methods to enumerate through
each returned object.

Iterators
Commands that retrieve a single record from the server block the calling thread in the Execute() method until
the data arrives. The data is then put into a record object and returned. Other commands, like select statistics,
can potentially return hundreds of records. If the Execute() method blocks until all records are returned, it can
take longer to receive any feedback. If the records are all returned in one large block instead of being consumed
one at a time, the computer slows down.
To solve these problems, commands that potentially retrieve multiple records return an iterator object as soon
as the first record arrives. As data is returned, a background thread automatically appends to the iterator. The
iterator has a connection to the server and the command object is not involved. This method allows you to
process records as they arrive. The following example demonstrates the select process command returning a
process iterator:
CDSelectProcCmd cmd;
CDProcIterator it = cmd.Execute(node):

Accessing Iterator Records

The iterator keeps an internal list of all records returned from the server. Use the following commands to
control iterator records:

© Copyright IBM Corp. 2011 19

 • HasMore()—Call this method to determine if any records are available in the list.

Note: You must always call HasMore() before calling GetNext(). It is not legal to call GetNext() if there are
no records.
• GetNext()—If HasMore() returns TRUE, obtain the next record in the list using this command. It removes
the next record from the list and returns it.
When all records are received from the server, the server notifies the iterator that the command is complete.
After all records are removed using GetNext(), HasMore() returns FALSE.
If the iterator’s list is empty, but the server has not notified the iterator that the command is complete, the
iterator cannot determine whether there are more records. In this case, HasMore() blocks until more records
are received from the server or a completion notification is received. Only then can the iterator return TRUE
or FALSE.
The following is an example of accessing statistics records using an iterator:
CDSelectStatCmd cmd;
CDStatIterator it = node.Execute (cmd);
while (it.HasMore()) {
CDStatistic stat = it.GetNext();
// use the statistics object }

Execute Sterling Connect:Direct Commands

Command Group classes execute Sterling Connect:Direct commands against Sterling Connect:Direct nodes.
Class Description
CDCommand
The base class for all Sterling Connect:Direct command objects. It wraps the parser within a class
and enables methods for data manipulation. Each derived class provides an Execute() method
to execute the command and return the resulting data or object.
If the result is several items, the command object returns a iterator object that holds the data.
The following CDCommand class definition shows the type of methods available in this class:
Class
CDCommand
{
public:
// Constructor for CDCommand
CDCommand(LPCTSTR pCommand=NULL);
virtual ~CDCommand();
virtual void ClearParms();
void SetCommand(const CString& strCmd);
virtual CString GetCommand() const;
virtual CString GetKQC() const;
// Execute() methods are provided by each
// derived command class.

CDSelectStatCmd Derived from the CDCommand base class, it enables you to set the SELECT STATISTICS
parameters. When you call the Execute() method, an iterator data object is dynamically created
and attached to the connection assigned by the CDNode object to execute the command.

20 SDK Programmers Guide

 Class Description
CDSelectProcCmd
Derived from the CDCommand base class, it enables you to set the SELECT PROCESS
parameters. When you call the Execute() method, the CDProcIterator object is created dynamically
and attached to the connection assigned to execute the command.
The following example demonstrates the CDSelectProcCmd class:
CDSelectProcCmd cmd;
CDProcIterator it = node.Execute(cmd);
while (it.HasMore()) {
CDProcess proc = it.GetNext();
// use the process }

CDChangeProcCmd Derived from the CDCommand base class, it enables you to set the CHANGE PROCESS
parameters. When the Execute() method is called, an iterator data object is dynamically created
and attached to the connection assigned to execute the command. A CDProcIterator is attached
to the iterator data and returned from the Execute() method.
CDDeleteProcCmd Derived from the CDCommand base class, it enables you to set the DELETE PROCESS
parameters. When the Execute() method is called, a CDProcData object is dynamically created
and attached to the connection assigned to execute the command. A CDProcIterator is attached
to the iterator data and returned from the Execute() method.
CDSelectMsgCmd Derived from the CDCommand base class, it enables you to set the SELECT MESSAGE
parameters. When you call the Execute() method, the command is executed and the resulting
message text is stored in the internal CDMessage object
CDStopCmd Derived from the CDCommand base class, it enables you to set the STOP parameter. When you
call the Execute() method, the command is executed.
CDSubmitCmd Used for submitting a Process object for execution on a node. It enables you to set the options
of the SUBMIT command and then execute the command on a node. When you call the Execute()
method, a CDProcess object is dynamically created and attached to the connection assigned to
execute the command. The following example demonstrates the CDSubmitCmd class:
.
.
.
CDSubmitCmd cmd;
cmd.SetFile ("myproc.cdp");
CDProcess proc = node.Execute(cmd);
proc.WaitForCompletion();
.
.
.

CDTraceOnCmd Derived from the CDCommand base class, it enables you to set and retrieve trace options from
the Sterling Connect:Direct node. The TraceOnCmd class handles all the options available from
the TRACEON command. The Execute() method returns a CDTrace object that contains the
current trace state.
CDTraceOffCmd Derived from the CDCommand base class, it enables you to clear trace options from the Sterling
Connect:Direct node. The CDTraceOffCmd class handles all of the options available from the
TRACEOFF command. You call methods to clear the desired trace parameters and then call the
Execute() method. The Execute() method returns a CDTrace object that contains the current
trace state.

© Copyright IBM Corp. 2011 21

Manage Exception Conditions
Exception Group classes manage exception conditions. Sterling Connect:Direct generates Exception Group
classes if an exception condition is encountered while a request is being processed. Following is an exception
scenario where a message is pushed into the exception before the initial throw.
Function A calls Function B, and Function B calls Function C. Function C is a helper routine called by many
routines so it does not include information specific to a task. Since the exception occurred in C, it throws the
exception. A message describing the error is added and flagged as a technical message.
Function B traps the exception. A message describing the error is added and flagged as a user message. User
messages are displayed in dialog boxes. For example, a user message reads: Communication with the server
has been lost.
The CDMsgException class stores the messages as an array of strings. The messages are stored in a last-in
first-out (LIFO) order because messages added later are more general as the exception moves up the call stack.
Following is a description of the Exception Group classes:
Class Description
CDMsgException The base exception class for all Sterling Connect:Direct exception objects. It
provides a message stack for troubleshooting.
CDConnectionException This exception is generated when communication with the node is lost or
cannot be established.
CDCommandException Generated when an object cannot be executed because parameters are invalid,
including a submitted Process containing errors.
CDLogonException Generated if the Sterling Connect:Direct node rejects the user ID and password
supplied in the logon attempt. You can respond to this exception by prompting
the user for the correct logon information.

Manage Administrative Functions

Helper Group classes provide common functionality, such as dialog boxes and thread creation and termination.

Manage Administrative Functions

Class Description

CDLogonDlg
The Sterling Connect:Direct common logon dialog box enables you to write your own logon
applications. The CDLogon dialog box enables you to change the node, the user ID and
password to connect to the Sterling Connect:Direct node as well as enable the Remember
Password check box, click the Configure button to save new server logon information and
change the title.
Below are the components of the CDLogonDlg class:
Node—Specifies the Sterling Connect:Direct node to which the user wants to logon.
userid—Specifies the user ID for the Sterling Connect:Direct node.
Password—Specifies the password defined for the user ID.

22 SDK Programmers Guide

 Class Description

Remember Password—Specifies whether the user wants the password to persist after the
user logs off. If the check box is enabled, the password is retrieved to set the password field
of the dialog box when the logon dialog is displayed. This prevents the user from having to
re-type the password information for the session. Enabling the check box also specifies
whether or not to write the password information as nonvolatile data. Nonvolatile keys persist
after the user logs off. If the user does not enable the Remember Password check box, the
password only persists until the user logs off.
The Sterling Connect:Direct Logon dialog box does not perform the logon. It captures the
entries and returns them to the calling program.
Normally, the programmer creates a CDLogon dialog box, sets the parameters, and calls the
DoModal() function to display and run the dialog box. If the user clicks the OK button, then
the CDLogonDlg class returns IDOK and a logon is attempted using the supplied connection
information. If the user clicks the Cancel button, the CDLogonDlg class returns IDCANCEL
and the logon is cancelled.
After a user successfully logs on to the Sterling Connect:Direct node, the connection
information is written to the Registry under the HKEY_CURRENT_USER key.

CDExceptionDlg Displays the exception dialog box. The dialog box displays the information in the exception
object

CDThread Coordinates the clean termination of threads and provides a thread class that can unblock
object

CDBeginThread Creates a worker thread for use with API objects.

Return Values A pointer to the newly created thread object.

Create A Thread Example

The following example illustrates how to create a thread:
void SomeFunc()
{
CDThread* pThread = CDBeginThread(ThreadFunc);
} void ThreadFunc(LPARAM lParam)
{
CSomeCmd cmd(...);
CDProcess proc = cmd.Execute(...);
DWORD dwId = proc.GetId();
SetDlgItemInt(IDC_SOMECONTROL, (int)dwId);
}

Terminate A Thread
In the preceding sample code, the only blocking that takes place is in the Execute() function. Execute() blocks
until the Process information returns from the server. To terminate the thread without waiting, call
CDThread::Exit, which signals any blocking CD objects in the thread to stop blocking and throw a thread exit
exception. In the previous example, if CDThread::Exit is called, an exception is thrown, and no return object
is returned from the Execute() function.

Note: It is not possible for one thread to throw an exception in another. CDThread::Exit sets flags in the
CDThread object that other CD objects use.

© Copyright IBM Corp. 2011 23

 When CDThread::Exit is called, CDThread::IsExiting returns TRUE. You can use this method in loops to
determine when to exit because CD objects only throw the exception when they are blocking.

Caution: Do not call the Win32 TerminateThread. TerminateThread does not give the thread a chance to shut
down gracefully. Calling TerminateThread can corrupt the state of the CD objects. CD objects use critical
sections and other resources that must be managed carefully.

Catch the Exception

It is not necessary to catch the CDThreadDeath exception. If not caught, the exception unwinds the stack,
destroying all objects on the stack, and the CDThread object itself handles the exception. To provide clean-up
for heap allocated items, the exception can be caught. Rethrowing the exception is not required.

Multithreaded Access and Blocking

Because the Sterling Connect:Direct C++ Class API uses multiple threads, the API objects are thread safe.
The API objects provide efficient blocking for use in multithreaded programs.

Objects On The Stack

Use the stack to ensure efficiency and reduce complexity.
C++ programs that make good use of exceptions move as much data from the heap to the stack as possible.
This ensures that destructors run and memory is released when an exception occurs. It also reduces the
complexity of the program by eliminating many pointers, reducing the chances of memory leaks, and letting
the compiler ensure that objects are valid (as opposed to pointers that could be NULL or bad).
To ensure objects are used on the stack efficiently, most CD objects store their data externally. The following
example is of an iterator object that holds 500 statistics records:
When the iterator is created, an iterator data object is also created to hold the records. The data object also has
a reference count that indicates how many objects are using the data. When an object is copied, the new object
(the copy) is linked to the data and the reference count of the data object is incremented. There are still only
500 records (not 1000), and the reference count is now 2.
When connected objects are destroyed, they decrement the reference count in the data object. When the reference
count reaches 0, the data object is also destroyed. The following figure provides an example of the efficiency
possible when shared data is copied:
1. void Func()
2. (
3. Iterator itFinal = CreateIterator();
4. }
5.
6. Iterator CreateIterator()
7. {
8. CSomeCmd cmd(...);
9. Iterator itLocal = node.Execute(cmd);
10. return itLocal;
11. }

24 SDK Programmers Guide

 On line 3 the sample code calls the CreateIterator() function. The CreateIterator() function returns an iterator,
called itLocal. This iterator is created on line 9 and returned on line 10.
At line 11 the C++ compiler creates a temporary copy of itLocal before destroying it. As part of the copy, the
iterator data reference count is incremented to 2. When itLocal is destroyed, the reference count drops to 1 so
that the records are not deleted.
Next, the C++ compiler constructs itLocal on line 3 by passing the temporary to its copy constructor. The
reference count is again incremented to 2 because both iterators are pointing to it. The temporary is then
destroyed, reducing the reference count to 1.
The result is that an unlimited number of records are passed to the stack with little more than the copying of
two pointers and some reference counting.

© Copyright IBM Corp. 2011 25

 Apply the ActiveX Control Interface

Submit Process
The Sterling Connect:Direct CDSubmit control is a command line control that submits Processes to the server.
Because submitting a Process can be a lengthy procedure, the Execute command returns immediately. When
a Process is submitted and the server responds, or a time-out occurs, the client is notified through the
SubmitStatus event. Additionally, the client can request notification when the Process has completed on the
server. Properties for the CDSubmit control follow:
Property Description
Node=nodename The name of the node that you want to connect to. The node name must be valid in the
Microsoft Windows system Registry.
User=userid The user ID used to log on to the Sterling Connect:Direct node.
Password=password The password used by the user ID to log on to the node.
Text=text The text of the Process.

Methods
Use the following methods to submit a process:
Method Description

Execute(BOOL bWait) Submits the Process to the server. An event is fired when the server responds to
notify the client of the status of the submit. If bWait is TRUE, another event is fired
when the Process completes on the server.

SetSymbolic(symbolic, value) Sets the symbolic value for symbolic. Call for each symbolic in the Process.

ClearSymbolics Clears all symbolics. Call before submitting a Process to clear the previous values.

Events
The following events are activated by the CDSubmit control:

Submitted Describes whether the Process is accepted by the server.

26 SDK Programmers Guide

 Completed The ProcessComplete event is sent when the Process is no longer in the server’s queue.
Because more resources are required to wait on a Process, this event is only fired if
requested in the call to Execute.

Error
The standard error event. Possible codes are:
CTL_E_PERMISSIONDENIED—cannot log onto the node.
CTL_E_DEVICEUNAVAILABLE—cannot connect to the node.
CTL_E_OUTOFMEMORY—out of memory.
CTL_E_ILLEGALFUNCTIONCALL—an unknown error. The error message describes the
error.

Display Select Statistics Results

The CDStatistics control is a multi-column list that displays SELECT STATISTICS command results. The
CDStatistics control properties determine the node that you are connected to, logon information, and selection
criteria. The following figure shows the CDStatistics control where only the message ID and message text are
selected.

Properties
The following table lists the CDStatistics control properties:
Property Description

ColCount=nnnnn The number of columns to display. The range for the ColCount value is 1–32,000.

Col=nnnnn The current column. The range for the Col value is 1–32,000.

ColWidth=nnnnn The width of the current column (Col) in pixels. The range for the ColWidth value
is 0–32,000.

Header The column header text for the current column. Provide text for the value or leave
it blank.

© Copyright IBM Corp. 2011 27

 Property Description

Row=nnnnn... The current row. If set to 0, the current row is the header. The range for the Row
value is 0–Infinity, where the number of rows is limited only by memory.

RowCount=positive integer The number of rows in the list, not including the header. This field is read-only and
is determined by the number of records returned by the server.

Node=node name The name of the node to which you want to connect. The node name must be
valid in the Microsoft Windows NT system Registry.

User=userid The user ID used to log on to the Sterling Connect:Direct node.

Password=password The password defined to allow the user ID to log onto the node.

Field The statistics structure field the current column is displaying. Valid values are
Process Name, Process Number, Condition Code, Feedback, MsgId, MsgText,
MsgData, LogDateTime, StartDateTime, StopDateTime, Submitter, SNode, RecCat,
and RecId.

ccode=(operator, code) Selects statistics records based on the completion code operator and return code
values associated with step termination. The condition code operator default is
eq. You must specify the return code. Refer to dfile=destination filename | (list)
below for valid operators and values.

dfile=destination filename | (list)

Searches all copy termination records (CAPR category, CTRC record ID) to find
those with a destination file name matching the file name or list of file names
specified.
This parameter is not supported in a UNIX environment.

pname=Process name | generic | (list) Selects Process statistics by Process name, a generic name, or a list of names.
The name can be 1–8 alphanumeric characters long.

pnumber=Process number | (list) Selects statistics by Process number or a list of Process numbers. Sterling
Connect:Direct assigns the Process number when the Process is submitted.

reccat=caev | capr | (caev , capr)

Selects statistics based on whether the record category is related to events or to
a Sterling Connect:Direct Process.
The default for this keyword depends on the other search criteria specified. If you
specify Process characteristics, such as Process name, Process number, or
Submitter, the default is capr. If you perform a general search using startt or stopt,
the default is caev and capr.
caev specifies that the retrieved statistics file records include those related to
Sterling Connect:Direct events, such as a Sterling Connect:Direct shutdown.
capr specifies that the retrieved statistics file records include those related to one
or more Sterling Connect:Direct Processes.

rnode=remote node name | generic | Selects statistics file records by remote node name, a generic node name, or a
(list) list of node names. The range for the remote node name is 1–16 alphanumeric
characters long.

sfile=filename | (list) Searches all copy Process Termination records (CAPR category, CTRC record
ID) to find those with a source file name matching the name or list of names you
specify.

28 SDK Programmers Guide

 Property Description

startt=([date | day] [, time])

Selects statistics starting with records logged since the specified date, day, or
time. The date, day, and time are positional parameters. If you do not specify a
date or day, type a comma before the time.
date specifies the day (dd), month (mm), and year (yy), which you can code as
mm/dd/yyyy or mm-dd-yyyy. If you only specify date, the time defaults to 00:00:00.
The current date is the default.
day specifies the day of the week. Values are today, yesterday, Monday, Tuesday,
Wednesday, Thursday, Friday, Saturday, and Sunday. If you specify a day of the
week, Sterling Connect:Direct uses the previous matching day.
time specifies the time of day coded as hh:mm:ss[am | pm] where hh is hours,
mm is minutes, and ss is seconds.You can specify the hour in either 12- or 24-hour
format. If you use the 12-hour format, then you must specify am or pm. The default
format 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=([date | day] [, time])

Retrieves statistics including records logged up to and including the specified date,
day, or time. The date, day, and time are positional parameters. If you do not
specify a date or a day, type a comma before the time.
date specifies the day (dd), month (mm), and year (yy), which you can code as
mm/dd/yyyy or mm-dd-yyyy. If you only specify date, the time defaults to 00:00:00.
The current date is the default.
day specifies the day of the week. Values are today, yesterday, Monday, Tuesday,
Wednesday, Thursday, Friday, Saturday, and Sunday. If you specify a day of the
week, Sterling Connect:Direct uses the previous matching day.
time specifies the time of day coded as hh:mm:ss[am | pm] where hh is hours,
mm is minutes, and ss is seconds.You can specify the hour in either 12- or 24-hour
format. If you use the 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.

submitter=(node name, userid) |

Selects statistics by the node name and user ID of the Process owner (submitter).
generic | (list)
You can also specify a generic name and user ID or a list of names and user IDs.
The maximum combined length, including the node name and user ID, is 66
characters.
Valid completion code operators for the ccode property are listed below:
eq | = | == Equal (default)
ge | >= | => Greater than or equal
gt | > Greater than
le | <= | =< Less than or equal
lt | < Less than
ne | != Not equal
Valid completion codes for the ccode property are listed below:
0 — Successful execution of the Process.

© Copyright IBM Corp. 2011 29

 Property Description

4 — A warning-level error was encountered. The statement probably completed

normally, but verify the execution results.
8— An error occurred during Process execution.
16 —A severe error occurred during Process execution.

recids=record id | (list)
Specifies selection by record ID or a list of record IDs. This parameter identifies
particular types of statistics records, such as a copy termination records or
initialization event records.
AUPR — Authorization file processing
CHGP — Change Process command issued
COAC — Communication activated
CMLT — CMGR listen thread terminated
CRHT — Sterling Connect:Direct copyright
CSTP — Child Process stopped
CTRC — Copy control record written
CTRM — Child Process terminated
CUKN — Child Process unknown status
CXIT — Child Process exited
DELP — Delete Process command issued
FLSP — Flush Process command issued
FMRV — Formatted Header (FMH) received
FMSD — Formatted Header (FMH) sent
GPRC — Get Process issued
IFED — If statement ended
IPPR — Initialization parameter processing
LIOK — Listen okay
NAUH — Node Authorization check issued
NMOP — Network map file opened
NMPR — Network map processing
NUIC — Sterling Connect:Direct Initialization complete
NUIS — Sterling Connect:Direct start initialization
NUT1 — Sterling Connect:Direct phase one termination complete status
NUT2 — Sterling Connect:Direct phase two termination complete status
NUTC — Sterling Connect:Direct termination complete
NUTR — Sterling Connect:Direct termination requested
NUTS — Sterling Connect:Direct termination started
PERR — Process error detected

30 SDK Programmers Guide

 Property Description

PFLS — Process flushed

PMED — Process Manager ended
PMIP — Process Manager Initprocs thread initialized

recids=record id | (list) (Continued)

PMMX — Process Manager Max Age thread initialized
PMRC — Process Manager release cell thread initialized
PMST — Process Manager started
PPER — Pipe error
PRED — Process ended
PSAV — Process saved
PSED — Process step detected
PSTR — Process started
RNCF — Remote server call failed
RTED — Run Task command completed
RJED — Run Job command completed
RFIP — Refresh command issued
SBED — Submit complete
SELP — Select Process command issued
SELS — Select Statistics command issued
SEND — Session end issued
SERR — System error
SHUD — Sterling Connect:Direct shutdown
SIGC — Signal caught
SMED — Session Manager ended
SMST — Session Manager started
SNHI — APPC started
SNMP — SNMP
STOP — Stop Sterling Connect:Direct command issued
SUBP — Submit command issued
TCPI — TCP started
TRAC — Trace command issued
UNKN — Unknown command issued
USEC — User Security check issued
xxxx — Record types identified by the first four characters of the message ID

© Copyright IBM Corp. 2011 31

 Methods
The CDStatistics control provides the following methods:
Method Description

BOOL Execute() Executes the SELECT STATISTICS command and stores the returned records in the control.
If the control was already retrieving records, the previous command is stopped and the old
records are removed from the control.

Clear Clears the existing records from the display. The Clear method does not stop retrieval.

Events
The following events are controlled by CDStatistics.
Method Description

Complete Sent after all records are retrieved.

Error
The standard error event. Possible codes are:
CTL_E_PERMISSIONDENIED—cannot log onto the node.
CTL_E_DEVICEUNAVALIABLE—cannot connect to the node.
CTL_E_OUTOFMEMORY—out of memory.
CTL_E_ILLEGALFUNCTIONCALL—an unknown error.

32 SDK Programmers Guide

 Apply Automation Servers

Apply Automation Servers

The Sterling Connect:Direct Automation Servers provide an automation wrapper around the Sterling
Connect:Direct SDK C++ classes.
The Automation Servers provide direct automation support for languages like Visual Basic. This section
provides a reference for the automation objects and information about applying them.

Create Virtual Servers Using the Node Factory

The node factory creates node objects, which act as virtual servers. Virtual servers represent a Sterling
Connect:Direct server (a node). The Automation Server Node Factory provides the following properties:
Property Description
Node Name The name of the node to connect to. The node name is set using the Sterling Connect:Direct Client
Connection Utility.
Userid The user ID to use when connecting to the node.
Password The password for the user ID to connect to the node.

The Sterling Connect:Direct Automation Server Node provides the following methods:
Method Description
SelectStats(criteria) Criteria specifies the complete SELECT STATISTICS string.
SelectProc(criteria) Criteria specifies the complete SELECT PROCESS string.
Submit(text) The text specifies the Process to SUBMIT.

Identify Active Processes

The Process object represents a Process running on the node. The records are returned as Process objects,
stored in a ProcCollection container. The Sterling Connect:Direct Automation Server Process object provides
the following properties:

© Copyright IBM Corp. 2011 33

 Property Type Description

ProcessName String The Process name.

ProcessNumber Long The Process number assigned by Sterling Connect:Direct when the
Process is placed in the TCQ.

ConditionCode Long The return code.

Feedback Long Provides additional return code information.

MsgId String The message identifier.

MsgText String The message text field.

MsgData String Message substitution fields.

LogDateTime Date The logged time stamp.

SchedDateTime Date The date and time the Process is scheduled to be submitted.

SubmitNode String The name of the node from which the Process was submitted.

Submitter String The user ID of the person submitting the Process.

PNode String The primary or controlling node in the Process.

SNode String The secondary or partner node in the Process.

Status String The status of the Process in the queue.

Retain String Specifies whether the Process is to be retained in the TCQ for future
submission.

Hold String The TCQ hold status of the Process.

Class Long The session class on which the Process is executing.

Priority Long The TCQ selection priority of the Process.

ExecPriority Long The operating system execution priority of the Process.

Queue String The logical queue where the Process is currently located (Execution,
Hold, Wait, or Timer).

Step Name String The currently executing step of the Process.

LocalNode String Specifies whether the primary or secondary node is the local node
and has primary control.

FromNode String Specifies whether the primary or secondary node is the source node
in a copy.

SimpleCompress Boolean Specifies whether to perform repetitive character compression.

ExtendedCompression Boolean Specifies whether to perform repetitive string compression.

Checkpoint Boolean Specifies the use of checkpointing in a copy step.

Restart Boolean Specifies whether the Process is restarted.

SourceFile String The name of the source file.

TotalBytes Long The number of data bytes read or written.

TotalRecs Long The number of data records read or written.

34 SDK Programmers Guide

 Property Type Description

SentBytes Long The number of data bytes sent.

Sent RUs Long The number of RU bytes sent.

DestFile String The name of the destination file.

Identify Statistic Records

The Statistic object represents the records in the statistics database. They are returned from a SELECT
STATISTICS query. The Sterling Connect:Direct Automation Server Statistic object provides the following
properties:
Property Data Type Description

ProcessName String The Process name.

ProcessNumber Long The Process number assigned by Sterling Connect:Direct when the Process is
placed in the TCQ.

Feedback Long Provides additional return code information.

MsgId String Message identifier.

MsgText String Message text.

MsgData String Message substitution fields.

LogDateTime Date The logged time stamp.

StartDateTime Date The start time stamp.

StopDateTime Date The stop time stamp.

Submitter String The submitter’s user ID.

SNode String The secondary node name.

RecCat String The record category.

RecId String The record identifier tag.

GetAuditField String
Returns the audit field value.
The GetAuditField() function supports the following audit information field names:

"Step Name"
"Primary Node Name"
"Secondary Node Name"
"Link Fail"
"Translation"
"Status"
"Function"
"Member Name"
"Sysopts"
"Bytes Read"
"Records Read"
"Bytes Sent"
"RUs Sent"

© Copyright IBM Corp. 2011 35

 Property Data Type Description

"Bytes Written"
"Records Written"
"Bytes Received"
"RUs Received"
"RU Size"
"Local Condition Code"
"Local Message ID"
"Other Condition Code"
"Other Message ID"
"PNode Accounting Info"
"SNode Accounting Info"
"Local Node"
"Retain"
"Class"
"Priority"
"Execution"
"Standard Compression"
"Extended Compression"
"Checkpoint"
"Scheduled Date/Time"
"Start Date/Time"
"Stop Date/Time"
"Submit Date/Time"
"From Node"
"Queue"
"Restart"
"Function"
"Source File"
"Source Disposition #1"
"Source Disposition #2"
"Source Disposition #3"
"Destination File"
"Destination Disposition #1"
"Destination Disposition #2"
"Destination Disposition #3"
"Hold"
"Substitution String"
"Submitter Node"

Use Automation Objects

Create node objects, select processes, and select statistics using automation objects.

36 SDK Programmers Guide

 This topic explains how to use the node factory and nodes, select statistics, and select Processes. The Sterling
Connect:Direct automation objects use late binding, so you must dimension your variables as type Object.

Create Node Objects

The Sterling Connect:Direct node factory creates node objects. These node objects serve as virtual servers and
represent a connection to a Sterling Connect:Direct server (node).
To obtain a connection (and therefore a node), you must use the node factory. Create the node factory using
the ProgID CD.NodeFactory:
Dim factory as Object
Set factory = CreateObject (“CD.NodeFactory”)

To determine the node you want to connect to, set the properties of the factory object. Next, call CreateNode
to connect to the node. If the connection is successful, a node object returns. Otherwise, an error is thrown
indicating the cause of the problem.
factory.NodeName = “CD.Node1"
factory.UserId = “user1"
factory.Password = “password”
{
Dim node as Object
Set node = factory.CreateNode()

The node name refers to the name used by the Client Connection Utility. You must set up the nodes that you
want to connect to using the Client Connection Utility prior to using the Sterling Connect:Direct SDK.

Node Usage
The node object represents the connection to a Sterling Connect:Direct node. Using the node enables you to
select statistics or Processes.

Select Processes
To select Processes, you must first format a select Process command and pass it to the SelectProc method. The
records return as Process objects and are stored in the ProcCollection container. Because a background thread
populates the collection, it is returned to the caller before it is completely filled. Therefore, the only access
method available is using the For Each construct.

Note: The usual Count property is not available because the count is not known until all records are returned.
Dim procs as Object ; the process collection
Dim proc as Object ; each process record
Set procs = node.SelectProc ("SELECT PROCESS ")
For Each proc in procs
Debug.Print proc.ProcessName
Next proc

Select Statistics
To select statistics records, you must format a select statistics command and pass it on to the SelectStats method
of the node. The records return as Statistic objects stored in a StatCollection container. Because a background
thread populates the collection, it returns to the caller before it is completely filled. Therefore, the only access
method available is using the For Each construct.

© Copyright IBM Corp. 2011 37

 Note: The usual Count property is not available because the count is not known until all records are returned.
Dim stats as object ; the Statistics collection
Dim stat as Object ; each statistic record
Set stats = node.SelectStats ("SELECT STATISTICS")
For Each stat in stats
Debug.Print stat.RecId
Next stat

Because the server can send records slowly, the interface can be jerky while reading records. Because records
are read using a background thread, it useful to select the statistics before time-consuming tasks like constructing
windows. This method enables the server to send records in background.

Automation Class Errors

The automation classes use the standard Visual Basic error-handling mechanism. When an error is raised in
an automation object, no real value is returned from the function. For example, if an error is raised in the node
factory example in the Create an Object to connect to a Node topic (see related link below), the node does not
have a value (it has the default value of nothing) because CreateNode has not returned anything.
When the Sterling Connect:Direct automation objects raise an error, they set the error number to a Sterling
Connect:Direct SDK error value and store a description in the error text.

38 SDK Programmers Guide

Enhance Security and Automate File Opening
with User Exits

User Exits
You can customize Sterling Connect:Direct operations with user exits. User exits are user-defined dynamic
link libraries (DLLs) that are loaded and called when the user exit is enabled through an initialization parameter.
Two user exits are provided: one for enhanced security and one for automated file opening.

Apply Enhanced Security

Apply Passticket Support

Use passtickets to implement enhanced security. A passticket is a one-time password generated on the primary
node and passed to the secondary node within 10 minutes, where it is validated before further processing is
performed. Sterling Connect:Direct passticket support is implemented by the user as a user exit called from
the Sterling Connect:Direct session manager during Process execution. To enable the security exit, specify the
name or path name of the security exit DLL in the value of the security.exit parameter.
See Changing Sterling Connect:Direct for Microsoft Windows Settings in the IBM Sterling Connect:Direct
for Microsoft Windows System Guide or Sterling Connect:Direct for Microsoft Windows Help for a description
of the security.exit parameter. If the DLL is not in the search path of the server, then you must specify the fully
qualified file name of the DLL.
The user’s security exit must contain the GeneratePassticket() and ValidatePassticket() functions. The parameters
for these functions are defined in the userexit.h header file. The userexit.h header file is in the Sterling
Connect:Direct samples directory. If the security exit cannot be found or loaded, or if the addresses of the two
required functions cannot be resolved successfully, an error message is generated and Process execution
terminates.
• The passticket is only valid for 10 minutes after it is generated. As a result, the system clocks on the two
nodes should be synchronized.
• When generating passtickets, Sterling Connect:Direct for Microsoft Windows fills in the GENMSG_T
structure fields and passes the structure to the security exit. The security exit should generate the passticket,

© Copyright IBM Corp. 2011 39

 fill in the GENMSG_REPLY_T structure fields, and return an appropriate return code to Sterling
Connect:Direct.
• When validating a passticket, Sterling Connect:Direct for Microsoft Windows fills in the VALMSG_T
structure fields and passes the structure to the security exit. The security exit validates the passticket, fills in
the VALMSG_REPLY_T structure fields, and returns an appropriate return code to Sterling Connect:Direct.
If the passticket is successfully validated, Sterling Connect:Direct for Microsoft Windows continues as if the
Process is using a remote user proxy. A proxy must be defined on the remote node for the effective ID being
used on the SNODE for the Process.

Security Exit Structure

Following is a list of the security exit structures:
• GENMSG_T—Sends a message to the local node to allow the security exit to determine the user ID and
security token (passticket) to use for remote node authentication. The GENMSG_T contains:
• Submitter ID
• Local node ID and password
• Remote node ID and password
• Local node name
• Remote node name
• GENMSG_REPLY_T—The user exit GeneratePassticket() function fills the GENMSG_REPLY_T structure.
The GENMSG_REPLY_T contains:
• Status value of GOOD_RC (0) for success, or ERROR_RC (8) for failure.
• Status text message. If the status value is failure, then status text message is included in the error message.
• ID to be used for security context on the remote node.
• Passticket to use in conjunction with the ID for security on the remote node.
• VALMSG_T—The message sent to the remote node to allow the security exit to validate the user ID and
passticket. The VALMSG_T contains:
• Submitter ID
• Local node ID and password
• Remote node ID and password
• Local node name
• Remote node name
• ID to be used for security checking from the local node
• Passticket generated on the local node
• VALMSG_REPLY_T—The user ValidatePassticket0 function fills the VALMSG_REPLY_T structure. The
VALMSG_REPLY_T contains:
• GOOD_RC (0) if the reply was a success or ERROR_RC (8) for failure.
• Status text message. If the status value is failure, the status text message is included in the error message.
• ID to be used for security context the remote node side. This value may or may not be the same ID as in
the generate message.
• Passticket to use in conjunction with ID for security on the remote node.

Security Exit Sample Code

The following header file and sample code files for passticket implementation are copied to X:\installation
directory\Server\samples during the installation. You can use them as examples to follow in implementing
your real-life security exit.

40 SDK Programmers Guide

 • userexit.h—Contains defined constants used for passtickets, the structures that are passed to the passticket
functions, and the function prototypes.
• usersamp_skel.c—Consists of the GeneratePassticket() and ValidatePassticket() functions. The
GeneratePassticket() function replies with a hard-coded ticket, fills in the structure, and returns a valid return
code. It demonstrates what should be input and output by the exit. The ValidatePassticket() function returns
a good return code indicating that the passticket passed in is valid. There is no real checking done in this
routine.
• userexit_samp.c—Demonstrates a sample implementation of passticket support. It works if the same exit is
on both sides. The GeneratePassticket() and ValidatePassticket() functions call the Passtk() function which
performs the actual generation, or validation of the passticket.
The sample user exit can be compiled and linked into a DLL using Microsoft Visual C++. The userexit_samp.sln
and userexit_skel.sln files can be found in the same samples directory where userexit_samp.c and userexit_skel.c
is found.The exit was tested using Microsoft Visual Studio 2008.

Apply Automated File Opening

Use the file open exit feature to override the values specified in the COPY statement. The file open exit is an
initialization parameter (file.exit) that you can set to point to a user-written DLL. You can customize Sterling
Connect:Direct COPY operations by defining values in the file open exit DLL that override the COPY statement
parameters.

Apply the File Open Exit

Sterling Connect:Direct file open support is implemented as a user exit called from the Sterling Connect:Direct
session manager during Sterling Connect:Direct COPY statement execution. To enable the file open exit,
change the value of the file.exit initialization parameter to the name or path name of the file open exit DLL.
Refer to Changing Sterling Connect:Direct for Microsoft Windows Settings in the IBM Sterling Connect:Direct
for Microsoft Windows System Guide or Sterling Connect:Direct for Microsoft Windows Help for a description
of the file.exit parameter. If the DLL is not in the search path of the server, then you must specify the fully
qualified file name of the DLL.
The user’s file open exit must contain the FileOpen() function. The parameters for this function are File_Open
and File_Open_Reply. These parameters are pointers to corresponding structures in the userexit.h header file.
The userexit.h header file is in the Connect:Direct samples directory.

File Open Exit Structures

The file open exit contains the following types of structures:
• FILE_OPEN: The FILE_OPEN structure contains the information that implements the file open user exit.
The FILE_OPEN structure contains the following components:
• int oflag—Flags that Sterling Connect:Direct uses to open the file.
• int srcdstflag—Specifies whether the file is a source file (the file to read) or a destination file (the file to
write to).
• char user_name[MAX_USER_NAME]—Specifies the name of the user that submitted the Process.
• COPY_T copy_ctl—Points to the Sterling Connect:Direct Copy Control Block data structure that contains
information concerning the COPY operation about to be performed.
• COPY_SYSOPTS_T cp_sysopts—Points to the Sysopts data structure that contains a representation of all
of the COPY operation sysopts that Sterling Connect:Direct supports. Refer to the Sterling Connect:Direct
Process Web site for more information about COPY sysopts.

© Copyright IBM Corp. 2011 41

 • FILE_OPEN_REPLY: The FILE_OPEN_REPLY structure contains information that specifies whether the
file exit operation succeeded. The FILE_OPEN structure contains the following components:
• HANDLE hFile—Contains a valid file handle if the file was opened successfully.
• char filename[MAX_FILE_NAME_LEN]—Contains the actual name of the file opened by the file open
exit.

Access Sample Code

The following header file and sample code files for file open exit implementation are copied to X:\installation
directory\Samples during Sterling Connect:Direct for Microsoft Windows installation.
• userexit.h
• FileOpenDLL.CPP

42 SDK Programmers Guide

 Structure Types

Structure Types
Following is a list of the common C and C++ Class interface structures, constants, and their descriptions.
• NETMAP_DESC_STRUCT Structure
• USER_STRUCT Structure
• MESSAGE_STRUCT Structure
• NETMAP_MODE_SNA Structure
• NETMAP_MODE_TCP Structure
• NETMAP_NODE_STRUCT Structure
• NETMAP_PATH_STRUCT Structure
• PROCESS_STRUCT Structure
• NODE_STRUCT Structure
• STATISTICS_STRUCT Structure
• TRACE_STRUCT Structure
• TRANSLATE_STRUCT Structure
All of the common C and C++ Class API structures are contained within the CONNDIR.H header file.

NETMAP_DESC_STRUCT Structure
The NETMAP_DESC_STRUCT structure contains the Netmap Node Description information. Use this
structure to retrieve and set the Netmap Node Description information.

Structure
struct Netmap_Desc_Struct
{
TCHAR Name[MAX_NODE_NAME_LEN+1];
TCHAR ContactPhone[MAX_PHONE_NUMBER+1];
TCHAR ContactName[MAX_CONTACT_NAME+1];
TCHAR Description[MAX_DESCRIPTION+1];

© Copyright IBM Corp. 2011 43

 };
typedef struct Netmap_Desc_Struct NETMAP_DESC_STRUCT;

Members
Member Description

Name [MAX_NODE_NAME_LEN+1] The node name.

ContactPhone [MAX_PHONE_NUMBER+1] The phone number of the person responsible for this node.

ContactName [MAX_CONTACT_NAME+1] The name of the person responsible for this node.

Description [MAX_DESCRIPTION+1] Node description information.

USER_STRUCT Structure
The USER_STRUCT structure contains the User Functional Authority information. Use this structure to
retrieve and set user functional authorities.

Structure
struct User_Struct
{
TCHAR Name [MAX_OBJECT_NAME+1];
TCHAR UpdateNetmap;
TCHAR UpdateUser;
TCHAR UpdateProxy;
TCHAR ChangeProcess;
TCHAR DeleteProcess;
TCHAR SelectProcess;
TCHAR SubmitProcess;
TCHAR SelectStats;
TCHAR SecureRead;
TCHAR SecureWrite;
TCHAR Stop;
TCHAR Trace;
TCHAR SelectNetmap;
TCHAR SelectMessage;
TCHAR Refresh;
TCHAR ProcessCopy;
TCHAR ProcessRunJob;
TCHAR ProcessRunTask;
TCHAR ProcessSubmit;
TCHAR InheritRights;
TCHAR TrusteeAssign;
TCHAR UpdateACL;
TCHAR FileAttributes;
TCHAR SNodeId;
TCHAR ExecutionPriority;
TCHAR ProcessSend;
TCHAR ProcessReceive;
TCHAR UpdateTranslation;

44 SDK Programmers Guide

 TCHAR DownloadDirectory[MAX_DIRECTORY_NAME+1];
TCHAR UploadDirectory[MAX_DIRECTORY_NAME+1];
TCHAR ProcessDirectory[MAX_DIRECTORY_NAME+1];
TCHAR ProgramDirectory[MAX_DIRECTORY_NAME+1];
};
typedef struct User_Struct USER_STRUCT;

Members
Member Description

UpdateUser Specifies permission to update other user functional authority.

UpdateProxy Specifies permission to update proxy user information.

ChangeProcess Gives a user permission to issue CHANGE PROCESS.

DeleteProcess Gives a user permission to issue DELETE PROCESS.

SelectProcess Gives a user permission to issue SELECT PROCESS.

SubmitProcess Gives a user permission to issue SUBMIT PROCESS.

SelectStats Gives a user permission to issue SELECT STATISTICS.

SecureRead Gives a user permission to read Sterling Connect:DirectSecure Plus network map fields.

SecureWrite Gives a user permission to modify Sterling Connect:Direct Secure Plus network map
fields.

Stop Gives a user permission to issue the STOP Sterling Connect:Direct server command.

Trace Gives a user permission to start and stop Sterling Connect:Direct tracing.

SelectNetmap Gives a user permission to get the network map objects from the Sterling Connect:Direct
server.

SelectMessage Gives a user permission to get Sterling Connect:Direct message information from the
Sterling Connect:Direct server.

Refresh Gives a user permission to execute the REFRESH INITPARMS commands.

ProcessCopy Gives a user permission to issue a COPY command within a Process.

ProcessRunJob Gives a user permission to issue a RUN JOB command within a Process.

ProcessRunTask Gives a user permission to issue a RUN TASK command within a Process.

ProcessSubmit Gives a user permission to issue a SUBMIT command within a Process.

Inherit Rights The Inherit Rights flag.

TrusteeAssign The Trustee Assign flag.

UpdateACL The Update ACL flag.

FileAttributes The File Attribute flag.

SNodeId The Remote Node ID flag.

ExecutionPriority Gives a user permission to change execution priority.

ProcessSend The Process Send flag.

ProcessReceive The Process Receive flag.

© Copyright IBM Corp. 2011 45

 Member Description

UpdateTranslation Gives a user permission to update the translation table information.

DownloadDirectory The default download directory.

[MAX_DIRECTORY_NAME+1]

UploadDirectory The default upload directory.

[MAX_DIRECTORY_NAME+1]

ProcessDirectory The default Process file directory.

[MAX_DIRECTORY_NAME+1

ProgramDirectory The default program file directory.

[MAX_DIRECTORY_NAME+1]

MESSAGE_STRUCT Structure
The MESSAGE_STRUCT structure contains the Sterling Connect:Direct message information. Use this
structure to retrieve the message information. It contains the unique message identifier.

Structure
struct Message_Struct
{
TCHAR MsgId[MAX_MESSAGE_ID+1];
int ConditionCode;
int Feedback;
TCHAR MsgText[MAX_MESSAGE_TEXT+1];
TCHAR MsgData[MAX_MESSAGE_DATA+1];
};
typedef struct Message_Struct MESSAGE_STRUCT;

Members
Member Description

MsgId [MAX_MESSAGE_ID+1] The message identifier that uniquely identifies this message.

ConditionCode The return code accompanying the message.

Feedback Additional return code information.

MsgText [MAX_MESSAGE_TEXT+1] The message text.

MsgData [MAX_MESSAGE_DATA+1] Message substitution fields.

NETMAP_MODE_SNA Structure
The NETMAP_MODE_SNA structure contains the Netmap SNA Mode information. This structure is part of
the NETMAP_MODE_STRUCT for SNA modes.

46 SDK Programmers Guide

 Structure
struct Netmap_Mode_Sna
{
long lMaxRUSize;
short MaxPacingSize;
short MaxNetSessLimit;
};
typedef struct Netmap_Mode_Sna NETMAP_MODE_SNA;

Members
Member Description

lMaxRUSize The maximum RU size.

MaxPacingSize The maximum pacing size.

MaxNetSessLimit The maximum net session limit.

NETMAP_MODE_TCP Structure
The NETMAP_MODE_TCP structure contains the Netmap TCP/IP Mode information. This structure is part
of the NETMAP_MODE_STRUCT for TCP/IP modes.

Structure
struct Netmap_Mode_Tcp
{
long lBufferSize;
long lPacingSendCount;
long lPacingSendDelay;
char tcp_crc[4];
};
typedef struct Netmap_Mode_Tcp NETMAP_MODE_TCP;

Members
Member Description

lBufferSize The buffer size.

lPacingSendCount Pacing send count.

lPacingSendDelay Pacing send delay.

char tcp_crc[4] Whether TCP CRC checking is on.

NETMAP_NODE_STRUCT Structure
The NETMAP_NODE_STRUCT structure contains the Netmap node information. Use this structure to retrieve
and set the Netmap node information.

© Copyright IBM Corp. 2011 47

 Structure
struct Netmap_Node_Struct
{
TCHAR Name[MAX_OBJECT_NAME_LEN+1];
BOOL bDetail;
int LongTermRetry;
long lLongTermWait;
int ShortTermRetry;
long lShortTermWait;
int MaxPNode;
int MaxSNode;
int DefaultClass;
int RemoteOSType;
TCHAR TcpModeName[MAX_OBJECT_NAME+1];
TCHAR TcpAddress[MAX_TCP_ADDRESS+1];
TCHAR SnaModeName[MAX_OBJECT_NAME+1];
TCHAR SnaNetName[MAX_NET_NAME+1];
TCHAR SnaPartnerName[MAX_PARTNER_NAME+1];
TCHAR SnaTPName[MAX_TPNAME+1];
};
typedef struct Netmap_Node_Struct NETMAP_NODE_STRUCT;

Members
Member Description

Name [MAX_OBJECT_NAME_LEN+1] The node name.

bDetail Specifies detail-included flag.

LongTermRetry Long-term retry interval.

lLongTermWait Long-term wait interval.

ShortTermRetry Short-term retry interval.

lShortTermWait Short-term wait interval.

MaxPNode The maximum number of local nodes.

MaxSNode The maximum number of remote nodes.

DefaultClass The default class.

RemoteOSType Remote node operating system type.

TcpModeName [MAX_OBJECT_NAME+1] The TCP/IP communications mode name.

TcpAddress [MAX_TCP_ADDRESS+1] The node's TCP/IP address.

SnaModeName [MAX_OBJECT_NAME+1] The SNA communications mode name.

SnaNetName [MAX_NET_NAME+1] The SNA net name.

SnaPartnerName [MAX_PARTNER_NAME+1] SNA partner name.

SnaTPName [MAX_TPNAME+1] The TP name.

48 SDK Programmers Guide

NETMAP_PATH_STRUCT Structure
The NETMAP_PATH_STRUCT structure contains the Netmap path information. Use this structure to retrieve
and set the Netmap path information.

Structure
struct Netmap_Path_Struct
{
TCHAR Name[MAX_OBJECT_NAME+1];
BOOL bDetail;
int Transport;
int Adapter;
BYTE Address[MAX_ADDRESS];
char CustomQLLC[MAX_CUSTOM_ADDRESS+1];
int Protocol;
TCHAR SnaProfileName[MAX_PROFILE_NAME+1];
TCHAR SnaLocalNetId[MAX_LOCALNETID+1];
TCHAR SnaPUName[MAX_PUNAME+1];
TCHAR SnaLUName[MAX_LUNAME+1];
int SnaLULocAddr;
int SnaLUSessLimit;
int TCPMaxTimeToWait;
int DialupHangon;
char DialupEntry[MAX_DIALUP_ENTRY+1];
char DialupUserid[MAX_OBJECT_NAME+1];
char DialupPassword[MAX_OBJECT_NAME+1];
TCHAR ModeName[MAX_OBJECT_NAME+1];
};
typedef struct Netmap_Path_Struct NETMAP_PATH_STRUCT;

Members
Member Description

Name [MAX_OBJECT_NAME+1] The path name.

bDetail The detail flag.

Transport Transport type.

Adapter Specifies the adapter.

Address [MAX_ADDRESS] The adapter address.

CustomQLLC[MAX_CUSTOM_ADDRESS+1] The custom or QLLC adapter address.

Protocol The protocol type.

SnaProfileName[MAX_PROFILE_NAME+1] The SNA profile name.

SnaLocalNetId [MAX_LOCALNETID+1] The SNA local net ID.

SnaPUName [MAX_PUNAME+1] The SNA PU name.

SnaLUName [MAX_LUNAME+1] The SNA LU name.

© Copyright IBM Corp. 2011 49

 Member Description

SnaLULocAddr The SNA LU local address.

SnaLUSessLimit The SNA LU session limit.

TCPMaxTimeToWait TCP maximum time to wait.

DialupHangon Number of seconds to stay connected after dialup hangon

completes.

DialupEntry[MAX_DIALUP_ENTRY+1] Dialup entry name.

DialupUserid[MAX_OBJECT_NAME+1] Dialup user ID.

DialupPassword[MAX_OBJECT_NAME+1] Dialup password.

ModeName [MAX_OBJECT_NAME+1] The mode name used by this path.

PROCESS_STRUCT Structure
The PROCESS_STRUCT structure contains the Sterling Connect:Direct Process information. This structure
is sent to the client from the Sterling Connect:Direct server upon accepting a Process for execution. It is also
sent in response to a SELECT PROCESS command. It contains the Process name, Process number, and queue.

Structure
struct Process_Struct
{
TCHAR ProcessName[MAX_PROCESS_NAME+1];
DWORD ProcessNumber;
int ConditionCode;
int Feedback;
TCHAR MsgId[MAX_MESSAGE_ID+1];
TCHAR MsgText[MAX_MESSAGE_TEXT+1];
TCHAR MsgData[MAX_MESSAGE_DATA+1];
time_t LogDateTime;
time_t SchedDateTime;
TCHAR SubmitNode[17];
TCHAR Submitter[65];
TCHAR PNode[17];
TCHAR SNode[17];
TCHAR Status[3];
TCHAR Retain;
TCHAR Hold;
int Class;
int Priority;
int ExecPriority;
TCHAR Queue[5];
TCHAR Function[6];
TCHAR StepName[9];
TCHAR LocalNode;
TCHAR FromNode;
BOOL bStandardCompression;
BOOL bExtendedCompression;

50 SDK Programmers Guide

 BOOL bCheckpoint;
BOOL bRestart;
TCHAR SourceFile[MAX_FILENAME+1];
TCHAR SourceDisp1;
TCHAR SourceDisp2;
TCHAR SourceDisp3;
__int64 ByteCount;
__int64 RecordCount;
__int64 XmitBytes;
long XmitRUs;
TCHAR DestFile[MAX_FILENAME+1];
TCHAR DestDisp1;
TCHAR DestDisp2;
TCHAR DestDisp3;
//SECURE_PLUS
BOOL bSecurePlusEnabled;
TCHAR EncAlgName[MAX_OBJECT_NAME];
BOOL bSignature;
};
typedef struct Process_Struct PROCESS_STRUCT;

Members
Member Description

ProcessName [MAX_PROCESS_NAME+1] The Process name.

ProcessNumber The Process number.

ConditionCode The return code.

Feedback Specifies additional return code information.

MsgId [MAX_MESSAGE_ID+1] The message identifier field.

MsgData [MAX_MESSAGE_TEXT+1] The message text field.

MsgData [MAX_MESSAGE_DATA+1] The message substitution data.

LogDateTime The logged time stamp.

SchedDateTime The scheduled time stamp.

SubmitNode [17] The submitter’s node.

Submitter [65] The submitter’s user name.

PNode [17] The primary node.

SNode [17] The secondary node.

Status [3] The current status.

Retain The retain flag.

Hold The hold flag.

Class The class.

Priority The current priority.

ExecPriority The current execution priority.

© Copyright IBM Corp. 2011 51

 Member Description

Queue [5] The current queue that contains this Process.

Function[6] The function executing in the Process.

StepName [9] The current step name.

LocalNode The local node flag.

FromNode The from node flag.

bStandardCompression The standard compression indicator.

bExtendedCompression The extended compression indicator.

bCheckpoint The checkpointing enabled indicator.

bRestart Restart indicator.

SourceFile [MAX_FILENAME+1] The source file name.

SourceDisp1 The source displacement 1.

SourceDisp2 The source displacement 2.

SourceDisp3 The source displacement 3.

ByteCount The total byte count.

RecordCount The total record count.

XmitBytes The sent byte count.

XmitRUs The sent RU count.

DestFile[MAX_FILENAME+1] The destination file name.

DestDisp1 The destination displacement 1.

DestDisp2 The destination displacement 2.

DestDisp3 The destination displacement 3.

bSecurePlusEnabled The Secure+ enabled flag.

EncAlgName[MAX_OBJECT_NAME] The effective encryption algorithm.

bSignature Specifies the effective signature setting.

NODE_STRUCT Structure
The NODE_STRUCT structure contains the Sterling Connect:Direct node information. This structure contains
the node name, the login information, operating system information, and protocol information. This information
is stored in the Registry and is sent to the client after successfully logging on.

Structure
struct Node_Struct
{
TCHAR Name[MAX_NODE_NAME_LEN+1];
TCHAR CDName[MAX_NODE_NAME_LEN+1];

52 SDK Programmers Guide

 TCHAR Server[MAX_OBJECT_NAME+1];
long ApiVersion;
long SecurePlusVersion;
int CompLevel;
int SelectedOSType;
int OSType
int SubType
TCHAR Userid[MAX_OBJECT_NAME+1];
TCHAR Password[MAX_OBJECT_NAME+1];
BOOL bTemporary;
BOOL bRememberPW;
int Protocol TCHAR TcpAddress[MAX_TCP_ADDRESS+1]
};
typedef struct Node_Struct NODE_STRUCT;

Members
Member Description

Name [MAX_NODE_NAME_LEN+1] The Sterling Connect:Direct node alias name.

CDName [MAX_NODE_NAME_LEN+1] The Sterling Connect:Direct node name.

Server [MAX_OBJECT_NAME+1] The file server name.

ApiVersion The API version.

SecurePlusVersion The Secure+ version; value is 0 if Secure+ is not supported.

CompLevel The KQV Communications Compatibility Level.

SelectedOSType The user-selected operating system type.

OSType The operating system type.

SubType Specifies subtype information.

Userid [MAX_OBJECT_NAME+1] The user name.

Password [MAX_OBJECT_NAME+1] The user-defined password.

bTemporary Specifies to hold the user information temporary.

bRememberPW Specifies to save the password in the Registry.

Protocol Protocol type.

STATISTICS_STRUCT Structure
The STATISTICS_STRUCT structure contains the Sterling Connect:Direct statistics information for a Process.
This structure is sent to the client as a result of a SELECT STATISTICS command.

Structure
struct Statistic_Struct
{
TCHAR ProcessName[MAX_PROCESS_NAME+1];
DWORD ProcessNumber;

© Copyright IBM Corp. 2011 53

 int ConditionCode;
int Feedback;
TCHAR MsgId[MAX_MESSAGE_ID+1];
TCHAR MsgText[MAX_MESSAGE_TEXT+1];
TCHAR MsgData[MAX_MESSAGE_DATA+1];
time_t LogDateTime;
time_t StartDateTime;
time_t StopDateTime;
TCHAR Submitter[65];
TCHAR SNode[17];
TCHAR RecCat[5];
TCHAR RecId[5];
};
typedef struct Statistic_Struct STATISTIC_STRUCT;

Members
Member Description

ProcessName [MAX_PROCESS_NAME+1] The Process name.

ProcessNumber The Process number.

ConditionCode The return code.

Feedback Additional return code information.

MsgId [MAX_MESSAGE_ID+1] The message identifier field.

MsgText [MAX_MESSAGE_TEXT+1] The message text field.

MsgData [MAX_MESSAGE_DATA+1] Message substitution data.

LogDateTime The logged time stamp.

StartDateTime The start time stamp.

StopDateTime The stop time stamp.

Submitter [65] The submitter’s user ID.

SNode [17] The secondary node name.

RecCat [5] The record category.

RecId [5] The record identifier tag.

TRACE_STRUCT Structure
The TRACE_STRUCT structure contains the trace information. Use this structure to retrieve the trace
information.

Structure
struct Trace_Struct
{
TCHAR cMainLevel;
TCHAR cCommLevel;

54 SDK Programmers Guide

 TCHAR cCMgrLevel;
TCHAR cPMgrLevel;
TCHAR cSMgrLevel;
TCHAR cStatLevel;
TCHAR szFilesize[MAX_FILENAME+1];
long cbFilesize;
BOOL bWrap;
BOOL bPNode;
BOOL bSNode;
int PNums[4];
TCHAR PNames[4] [MAX_PROCESS_NAME+1];
TCHAR DestNodes[4] [17];
};
typedef struct Trace_Struct TRACE_STRUCT;

Members
Member Description

cMainLevel MAIN trace level.

cCommLevel The COMM trace level.

cCMgrLevel CMGR trace level.

cPMgrLevel PMGR trace level.

cSMgrLevel The SMGR trace level.

cStatLevel STAT trace level.

szFilename[MAX_FILENAME+1] The trace file name.

cbFilesize The size of the trace file.

bWrap Specifies whether to wrap when cbFile is reached.

bPNode The PNODE trace flag.

bSNode The SNode trace flag.

PNums[8] Specifies an integer array of up to four Process numbers.

PNames[8] [MAX_PROCESS_NAME+1] The string array of Process names.

DestNodes[8] [17] The string array of destination node names.

TRANSLATE_STRUCT Structure
The TRANSLATE_STRUCT structure contains the translation table information. Use this structure to retrieve
and set the translation table information.

Structure
struct Translate_Struct
{
TCHAR Filename[MAX_OBJECT_NAME+1];
BYTE Table[256];

© Copyright IBM Corp. 2011 55

 TCHAR MsgId[MAX_MESSAGE_ID+1];
int ConditionCode;
int Feedback;
TCHAR MsgText[MAX_MESSAGE_TEXT+1];
TCHAR MsgData[MAX_MESSAGE_DATA+1];
};
typedef struct Translate_Struct TRANSLATE_STRUCT;

Members
Member Description

FileName [MAX_OBJECT_NAME+1] The name of the file where the translation information is stored.

Table [256] The actual translation table information.

MsgId[MAX_MESSAGE_ID+1] The message identifier that uniquely identifies a message.

ConditionCode The return code that accompanies a message.

Feedback Additional return code information.

MsgText[MAX_MESSAGE_TEXT+1 The message text.

MsgData[MAX_MESSAGE_DATA+1] The message substitution field.

56 SDK Programmers Guide

 Return Codes

C++ Class and the C API Functions Return Codes

CDAPI.H Return Code Values

This table describes the return code values defined in CDAPI.H.
Name Description

CD_NO_ERROR No error detected.

CD_ENDOFDATA No more data available.

CD_PARM_ERROR Invalid parameter detected.

CD_INITIALIZE_ERROR Initialization failed or initialization has not been performed.

CD_CONNECT_ERROR Error occurred during attach processing.

CD_CONNECT_CANCELLED Attach operation cancelled by the user.

CD_CONNECTED_ERROR Invalid Sterling Connect:Direct server name.

CD_DISCONNECT_ERROR Sterling Connect:Direct server disconnected from the client.

CD_NODENAME_ERROR The Name field not set and the default not found.

CD_USERID_ERROR Invalid user ID specified.

CD_ADDRESS_ERROR Invalid TCP/IP address.

CD_PROTOCOL_ERROR Invalid or unsupported protocol specified.

CD_HANDLE_ERROR Invalid handle.

CD_HANDLE_TYPE_ERROR The wrong handle type specified.

CD_LOGON_ERROR Error while logging on to the Sterling Connect:Direct server. The user ID or
password may be invalid.

CD_DIALOG_ERROR Dialog box not created correctly.

CD_CANCEL An error occurred creating the dialog box or retrieving the entered information.

CD_BUSY_ERROR Operation failed. Connection is currently busy.

© Copyright IBM Corp. 2011 57

 Name Description

CD_IDLE_ERROR Operation failed. Connection is currently idle.

CD_KQV_ERROR Invalid KQV stream detected.

CD_NOT_FOUND Object not found.

CD_ALREADY_EXISTS Object already exists.

CD_ALLOCATE_ERROR Allocation error occurred.

CD_NODE_ERROR Invalid network map node.

CD_PARSER_ERROR Parser detected an error.

CD_ACCESS_DENIED Object access denied.

CD_SEND_ERROR Error while sending error.

CD_RECEIVE_ERROR Error while receiving error.

CD_CONNECTION_ERROR A connection error occurred.

CD_REGISTRY_ERROR An error occurred while opening the Registry.

CD_TIMEOUT_ERROR Time-out value was reached.

CD_BUFFER_ERROR The buffer is not big enough to hold all of the items in the list.

CD_COMMAND_ERROR The command was not recognized.

CD_PROCESS_ERROR The Process status is HE, held in error.

CD_UNDEFINED_ERROR An unknown exception.

CD_NOT_SUPPORTED An unknown exception.

58 SDK Programmers Guide

 Notices

Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult
your local IBM representative for information on the products and services currently available in your area.
Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product, program, or service that does
not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility
to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The
furnishing of this document does not grant you any license to these patents. You can send license inquiries, in
writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte character set (DBCS) information, contact the IBM Intellectual
Property Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan Ltd.
1623-14, Shimotsuruma, Yamato-shi
Kanagawa 242-8502 Japan
The following paragraph does not apply to the United Kingdom or any other country where such provisions
are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES
THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,

© Copyright IBM Corp. 2011 59

 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer
of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made
to the information herein; these changes will be incorporated in new editions of the publication. IBM may
make improvements and/or changes in the product(s) and/or the program(s) described in this publication at
any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in any
manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials
for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange
of information between independently created programs and other programs (including this one) and (ii) the
mutual use of the information which has been exchanged, should contact:
IBM Corporation
J46A/G4
555 Bailey Avenue
San Jose, CA__95141-1003
U.S.A.
Such information may be available, subject to appropriate terms and conditions, including in some cases,
payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM
under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent
agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results
obtained in other operating environments may vary significantly. Some measurements may have been made
on development-level systems and there is no guarantee that these measurements will be the same on generally
available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual
results may vary. Users of this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published
announcements or other publicly available sources. IBM has not tested those products and cannot confirm the
accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to the suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice,
and represent goals and objectives only.
This information is for planning purposes only. The information herein is subject to change before the products
described become available. This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the names of individuals,
companies, brands, and products. All of these names are ficticious and any similarity to the names and addresses
used by an actual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs in

60 SDK Programmers Guide

 any form without payment to IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating platform for which the sample
programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore,
cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are
provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your
use of the sample programs.
Each copy or any portion of these sample programs or any derivative work, must include a copyright notice
as follows:
© IBM 2011. Portions of this code are derived from IBM Corp. Sample Programs.
© Copyright IBM Corp. 2011.
If you are viewing this information softcopy, the photographs and color illustrations may not appear.
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines
Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of
IBM or other companies. A current list of IBM trademarks is available on the Web at “Copyright and trademark
information” at www.ibm.com/legal/copytrade.shtml.
Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of
Adobe Systems Incorporated in the United States, and/or other countries.
IT Infrastructure Library is a registered trademark of the Central Computer and Telecommunications Agency
which is now part of the Office of Government Commerce.
Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel
SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries
in the United States and other countries.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the
United States, other countries, or both.
ITIL is a registered trademark, and a registered community trademark of the Office of Government Commerce,
and is registered in the U.S. Patent and Trademark Office.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its
affiliates.
Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc. in the United States, other
countries, or both and is used under license therefrom.
Linear Tape-Open, LTO, the LTO Logo, Ultrium and the Ultrium Logo are trademarks of HP, IBM Corp. and
Quantum in the U.S. and other countries.
Connect Control Center®, Connect:Direct®, Connect:Enterprise, Gentran®, Gentran:Basic®, Gentran:Control®,
Gentran:Director®, Gentran:Plus®, Gentran:Realtime®, Gentran:Server®, Gentran:Viewpoint®, Sterling
Commerce™, Sterling Information Broker®, and Sterling Integrator® are trademarks or registered trademarks
of Sterling Commerce, Inc., an IBM Company.
Other company, product, and service names may be trademarks or service marks of others.

© Copyright IBM Corp. 2011 61