Connect Direct For Microsoft Windows 4.7 Documentation
Connect Direct For Microsoft Windows 4.7 Documentation
Connect Direct For Microsoft Windows 4.7 Documentation
7 IBM
Documentation
Version 4.7
Sterling Connect:Direct for Microsoft Windows 4.7 IBM
Documentation
Version 4.7
This edition applies to Version 5 Release 2 of IBM Sterling Connect:Direct and to all subsequent releases and
modifications until otherwise indicated in new editions.
© Copyright IBM Corporation 1982, 2016.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Chapter 1. Connect:Direct for Microsoft Installation Overview . . . . . . . . . . 28
Windows Release Notes. . . . . . . . 1 Automate Installation . . . . . . . . . . . 37
Requirements . . . . . . . . . . . . . . 1 About Silent Installations . . . . . . . . . 37
Features and Enhancements . . . . . . . . . 3 Customize Initialization Information for a Silent
Special Considerations . . . . . . . . . . . 6 Installation . . . . . . . . . . . . . 38
Known Restrictions . . . . . . . . . . . . 6 CD_SRVR.INI Parameter Values . . . . . . 38
Restrictions for Sterling Connect:Direct for Customize Sterling Connect:Direct for Microsoft
Microsoft Windows . . . . . . . . . . . 6 Windows Configuration Information . . . . . 42
Restrictions for Related Software. . . . . . . 8 Run a Silent Installation . . . . . . . . . 42
Installation Notes . . . . . . . . . . . . . 9 Perform an Unattended Uninstallation . . . . 43
Installation Notes for Sterling Connect:Direct
Requester . . . . . . . . . . . . . . 9 Chapter 3. System Guide . . . . . . . 45
Installation Notes for Sterling Connect:Direct File Configure the Local Node . . . . . . . . . 45
Agent. . . . . . . . . . . . . . . . 9 Configuring the Sterling Connect:Direct Local
Sterling Connect:Direct Secure Plus for Microsoft Node . . . . . . . . . . . . . . . 45
Windows . . . . . . . . . . . . . . 10 Adding or Modifying a Local Node Definition . 45
Upgrading Guidelines . . . . . . . . . . . 10 Adding a User . . . . . . . . . . . . 46
Upgrading Guidelines for Sterling Connect:Direct Modifying a User ID . . . . . . . . . . 46
for Microsoft Windows . . . . . . . . . 10 Deleting a User . . . . . . . . . . . . 47
Upgrading Guidelines for Related Software. . . 11 Attaching to a Local Node . . . . . . . . 47
About Local Functional Authorities . . . . . 47
Chapter 2. Getting Started Guide . . . 13 Define Remote User Proxies . . . . . . . . 53
Prepare for the Installation of IBM Sterling Creating or Modifying a Remote User Proxy . . 54
Connect:Direct for Microsoft Windows . . . . . 13 Deleting a Remote User Proxy . . . . . . . 55
Requirements for Copying Files To and From Define and Manage the Sterling Connect:Direct
Network Servers. . . . . . . . . . . . 13 Network . . . . . . . . . . . . . . . 55
Configure Microsoft Windows User Privileges . . 14 Define and Manage the Sterling Connect:Direct
Customize a Sterling Connect:Direct Logon Network . . . . . . . . . . . . . . 55
Account . . . . . . . . . . . . . . 14 About Defining the Network Map . . . . . . 56
Configure TCP/IP Connectivity . . . . . . 15 Define Remote Node Information . . . . . . 56
Sterling Connect:Direct for Microsoft Windows Creating or Modifying a Remote Node Definition 57
Installation Worksheet . . . . . . . . . . 15 Creating or Modifying a Communications Path
Install and Configure Database Software. . . . 16 Definition . . . . . . . . . . . . . . 63
Automate the Sterling Connect:Direct for Defining a New Mode for a Communications
Microsoft Windows Installation . . . . . . . 16 Path . . . . . . . . . . . . . . . . 65
Configure SNA Connectivity. . . . . . . . 17 Deleting a Network Map Entry . . . . . . . 66
SNA Configuration Worksheet . . . . . . . 17 Validating a Network Map Entry . . . . . . 67
Sample Sterling Connect:Direct for z/OS Viewing a Network Map as Text . . . . . . 67
Network Map Entries . . . . . . . . . . 18 Applying a Network Map . . . . . . . . 67
XCA Token Ring: Switched Net Definitions . . . 19 Printing and Viewing Node and Network Map
XCA Token Ring: Independent LU Definition . . 20 Definitions. . . . . . . . . . . . . . 68
XCA Token Ring: Major Node Definition . . . 21 View the Sample Configuration Files . . . . . 68
Sample Sterling Connect:Direct APPLDEF . . . 21 Customizing Configuration Files . . . . . . 69
Sample Sterling Connect:Direct MODEENTS Adding an Encrypted Password for a User Proxy 69
(Mode Definitions) . . . . . . . . . . . 21 Validating Configuration Files for Use with
Sample VTAM Start Options (ATCSTRxx) . . . 22 Sterling Connect:Direct . . . . . . . . . 70
z/OS Network Map Example for VTAM. . . . 23 Applying Updated Configuration Information . . 70
Microsoft Windows Network Map Example . . 23 Stop Sterling Connect:Direct for Microsoft Windows 71
Access SNA Server Configuration Listing . . . 24 Stopping Sterling Connect:Direct for Microsoft
Access Communications Server Configuration Windows . . . . . . . . . . . . . . 71
Listing . . . . . . . . . . . . . . . 27 Stopping Sterling Connect:Direct for Microsoft
SNA Server/Host Configuration Worksheet . . 27 Windows from Sterling Connect:Direct Requester. 71
Installing in a Windows clustered environment . . 28 Stopping Sterling Connect:Direct for Microsoft
Install Sterling Connect:Direct for Microsoft Windows Using the Services Facility . . . . . 72
Windows . . . . . . . . . . . . . . . 28
Contents v
Sterling Connect:Direct for Microsoft Windows User Exits . . . . . . . . . . . . . 284
SDK Overview . . . . . . . . . . . . 251 Apply Enhanced Security . . . . . . . . 284
Edit Connection Settings . . . . . . . . . 253 Apply Automated File Opening . . . . . . 286
Edit Connection Settings with the Client Structure Types. . . . . . . . . . . . . 287
Connection Utility . . . . . . . . . . . 253 Structure Types. . . . . . . . . . . . 287
Start the Client Connection Utility . . . . . 253 NETMAP_DESC_STRUCT Structure . . . . . 287
Add and Delete Node Connection Definitions 254 USER_STRUCT Structure . . . . . . . . 288
Add a Node . . . . . . . . . . . . . 254 MESSAGE_STRUCT Structure . . . . . . . 290
Delete a Node . . . . . . . . . . . . 255 NETMAP_MODE_SNA Structure . . . . . . 291
Add a User . . . . . . . . . . . . . 255 NETMAP_MODE_TCP Structure . . . . . . 291
Delete a User . . . . . . . . . . . . 256 NETMAP_NODE_STRUCT Structure . . . . 292
Update Node Properties . . . . . . . . . 256 NETMAP_PATH_STRUCT Structure. . . . . 293
Define a Default Node or Default User . . . . 257 PROCESS_STRUCT Structure . . . . . . . 294
Import Registry Settings . . . . . . . . . 257 NODE_STRUCT Structure . . . . . . . . 297
Export Registry Settings . . . . . . . . . 258 STATISTICS_STRUCT Structure . . . . . . 298
Print Registry Settings Report . . . . . . . 258 TRACE_STRUCT Structure . . . . . . . . 298
Apply the C API . . . . . . . . . . . . 258 TRANSLATE_STRUCT Structure . . . . . . 299
The C Applications Programming Interface . . 258 Return Codes . . . . . . . . . . . . . 300
Compile and Debug . . . . . . . . . . 259 C++ Class and the C API Functions Return
Activate Tracing . . . . . . . . . . . 259 Codes . . . . . . . . . . . . . . . 300
Standard C API . . . . . . . . . . . 259
View Sample Programs . . . . . . . . . 261 Chapter 7. .Net SDK User Guide . . . 303
Apply the C++ Class Interface. . . . . . . . 261 Sterling Connect:Direct for Microsoft Windows
Compile and Debug . . . . . . . . . . 261 .Net SDK Overview . . . . . . . . . . . 303
Manipulate Nodes. . . . . . . . . . . 262 Sample Programs . . . . . . . . . . . . 303
Create an Object to Connect to a Node . . . . 263 Add the .Net Class Interface . . . . . . . . 304
Manage Connections . . . . . . . . . . 264 About Classes . . . . . . . . . . . . . 304
View Information . . . . . . . . . . . 264 Connect to a Sterling Connect:Direct for Microsoft
Control the Return of Information . . . . . 265 Windows Node. . . . . . . . . . . . . 304
Execute Sterling Connect:Direct Commands . . 266 Disconnect Nodes . . . . . . . . . . . . 305
Manage Exception Conditions . . . . . . . 267 Submit Processes . . . . . . . . . . . . 305
Manage Administrative Functions . . . . . 268 Manage Processes . . . . . . . . . . . . 305
Multithreaded Access and Blocking . . . . . 270 Retrieve Statistics . . . . . . . . . . . . 307
Objects On The Stack . . . . . . . . . . 270 Node Properties . . . . . . . . . . . . 307
Apply the ActiveX Control Interface . . . . . . 271 Process Class . . . . . . . . . . . . . 307
Submit Process . . . . . . . . . . . . 271 Process Properties . . . . . . . . . . . . 308
Display Select Statistics Results . . . . . . 272 Statistic Class . . . . . . . . . . . . . 309
Apply Automation Servers . . . . . . . . . 278 Statistic Properties . . . . . . . . . . . . 309
Apply Automation Servers . . . . . . . . 278
Create Virtual Servers Using the Node Factory 279
Notices . . . . . . . . . . . . . . 311
Use Automation Objects . . . . . . . . . 282
Trademarks . . . . . . . . . . . . . . 313
Enhance Security and Automate File Opening with
Terms and conditions for product documentation 314
User Exits . . . . . . . . . . . . . . 284
Requirements
Sterling Connect:Direct for Microsoft Windows has the following requirements.
Sterling Connect:Direct for Microsoft Windows and related software require the
following hardware and software.
Virtualization support
IBM® Aspera® High Speed Add-on for Sterling Connect:Direct® for Microsoft Windows uses
FASP(TM) (Fast and Secure Protocol) network transport to transfer files over high
bandwidth and high latency network connections. FASP support has been added for
interoperability with Sterling Connect:Direct for UNIX (V4.2.0.4 or later) and Sterling
Secure Proxy (V3.4.3.0 or later).
Option to automatically delete a process from the TCQ after all connection retries are
exhausted.
Adds an initialization parameter conn.retry.exhaust.action. The two valid values for this
parameter are hold and delete:
v Hold - Places Processes in the hold queue in Held in Error status after all retry
attempts are used. This is the default value and retains the prior behavior of
Connect:Direct.
v Delete - Causes Processes to be permanently deleted from the TCQ after all
short-term and long-term retries are exhausted.
This feature also adds a message ID LCPF003E: Process Retry exceeded for &pname
&pnum.
Connect:Direct Windows SDK for x64 bit Windows Platform in C++.
Adds 64-bit versions of CdCore.lib and CdCore.dll files in a new x64 folder. To build the
C++ samples for the x64 platform, remove your existing *.sln and *.vcxproj files from the
CPPSample1 and CPPSample2 folders before you apply this fix. Once the fix is applied,
start with opening the new *.vcxproj files.
Adds an initialization parameter conn.retry.exhaust.action. The two valid values for this
parameter are hold and delete:
v Hold - Places Processes in the hold queue in Held in Error status after all retry
attempts are used. This is the default value and retains the prior behavior of
Connect:Direct.
v Delete - Causes Processes to be permanently deleted from the TCQ after all
short-term and long-term retries are exhausted.
This feature also adds a message ID LCPF003E: Process Retry exceeded for &pname
&pnum.
The LCOA014I error messages provide more details about failed login attempts. This
feature adds the OS system error code as a feedback code (FDBK) and a specified user ID
to the message data for LCOA014I. Some typical error codes include:
v 1326: Login failure - unknown username or bad password.
v 1331: Login failure - account currently disabled.
v 1385: Login failure - the user was not granted the requested login type on this computer.
Concurrent sessions high water mark
The concurrent sessions high water mark count is the maximum number of sessions that
can run concurrently. This count is information only and it does not require any action
from the user. The high water mark count is logged each day at midnight local time and at
system shutdown in the SCNT record in Process statistics. A new LCNT001I message
provides the following information to the user: Concurrent Sessions High Water Mark
count of &MAX occurred at &TIME.
Increases the default window size of the control pad in Connect:Direct Requester.
Ability to create a configuration report from the CLI
Adds a parameter, cdconfig, to the traceon command. The configuration report is written
to a file named cdconfig.txt, which is created in the same folder as the specified trace file.
For example, enter the following command line in the CLI to create a configuration report
in C:\Temp\cdconfig.txt:
traceon file=C:\Temp\dummy.cdt config;
Connect:Direct Requester no longer overwrites the PNODE or SNODE when
$PNODE$="" or $SNODE$="" is found in REQUESTER_COMMENTS
Connect:Direct Secure Plus Administration tool rewrites a node record file only when
the user modifies the file.
In previous versions, the administration tool rewrote node record files if the user viewed
them but did not update their settings.
Sterling Connect:Direct for Windows Total Max Sessions enforcement
An initialization parameter, sess.total, was added to limit the total number of concurrent
sessions. Valid numeric values are 1-510. If a value is not specified, the value is the sum of
the values of sess.pnode.max and sess.snode.max initialization parameters.
The Connect:Direct server stores millisecond time resolutions on some of the existing time
stamps that are saved in its statistics logs. A Connect:Direct API client can opt in or out of
displaying the extra millisecond time resolution characters.
Addition of NIST SP800-131a and Suite B support for Sterling Connect:Direct UNIX and
Windows platforms.
Support for TSL 1.2 for Sterling Connect:Direct UNIX and Windows platforms.
Adds support for importing and exporting initialization parameters through the
Configuration Utility. To operate in silent mode, use the following commands:
– CdConfig.exe /Q /PInitparms.cfg /* Export */
Attention: Verify that the service is stopped before you run an import.
Attention: The node name and server.path initialization parameters cannot be changed and
are ignored during the import.
Applied removal of STS support for Sterling Connect:Direct for UNIX and Windows.
Provides for automated deployment of Sterling Connect:Direct for UNIX across the
enterprise with enterprise deployment tools such as IBM Tivoli® Endpoint Manager. For
more information, seeIBM Sterling Connect:Direct Enterprise Deployment Guide.
Adds 64-bit support for Sterling Connect:Direct for Microsoft Windows .NET SDK. The
.NET samples support building 32- and 64-bit versions. The x64 directory includes release
and debug builds of the 64-bit .NET SDK.
Enhances the PNODE Delete/Flush Process command to support stopping processes while
they are executing an SNODE Run Task step. For users of the Connect:Direct Command
Line Interface (CLI Direct.exe), note: The CLI’s DELETE PROCESS command is required to
remove an executing (EXEC) process from the queue. Additionally, one of the HOLD or
FORCE arguments to the DELETE PROCESS command must be set to YES. For example,
DELETE PROCESS FORCE=YES; /* Delete executing process from the queue */ DELETE
PROCESS HOLD=YES; /* Delete executing process and place it in the HOLD queue */The
default for both FORCE and HOLD is NO. Therefore, at least one must be specified and
set to YES in order for the process to be deleted when you use the CLI.
Increases the default maximum database size for IBM solidDB to 8000M.
Special Considerations
This section details special considerations to be aware of for your platform.
v Certain maintenance fixes should be applied to Sterling Connect:Direct for z/OS
to have the correct TLS protocol negotiation with Sterling Connect:Direct for
Microsoft Windows 4.7. It is suggested the you upgrade Sterling Connect:Direct
for z/OS with these four HIPER fixes: UI14876, UI14924, UI16043, UI16936. For
additional information, see http://www14.software.ibm.com/webapp/set2/
psearch/search?domain=psp and search for the FMID for CDZ/5.2 (HDGA520)
and select Upgrade STRCD520, Subset HDGA520 , then select Service
Recommendations for the most current list of HIPER fixes.
v The database retry feature retries a connection for up to eight minutes before a
failure is allowed to continue. When you use client applications like Sterling
Connect:Direct Requester, the application may appear to quit working. If this
occurs, check the event log for database errors indicating a retry is in progress. If
the retry is unsuccessful, you may need to recycle the Sterling Connect:Direct for
Microsoft Windows server.
v IBM solid DB
– If you do not install IBM solidDB as your database and would like to install it
at a later time, re-run setup.exe. You can also install the solidDB feature.
Known Restrictions
Sterling Connect:Direct for Microsoft Windows and its related software have the
following known restrictions.
Note: To disable temporary addresses in the Windows Vista OS, issue the
following command from a command prompt: netsh interface ipv6 set privacy
state=disabled. For other Windows operating systems, see the Microsoft Windows
documentation.
Installation Notes
Before you install Sterling Connect:Direct and its related applications, read all the
information in this section and follow all the guidelines.
v Complete any worksheets before installing Sterling Connect:Direct and its
related software.
v Review your security configuration to ensure compatibility with Sterling
products.
v Verify that you have the current updates for Sterling Connect:Direct for
Microsoft Windows, Sterling Connect:Direct Requester, Sterling Connect:Direct
for Microsoft Windows File Agent, and Sterling Connect:Direct Secure Plus for
Microsoft Windows.
v Review theIBM Sterling Connect:Direct for Microsoft Windows Getting Started Guide.
Upgrading Guidelines
Observe the following guidelines for upgrading Sterling Connect:Direct for
Microsoft Windows and its related software.
Sterling Connect:Direct for Microsoft Windows is installed under the local System
account.
Note: These privileges are stored locally, even if the computer is a member of a
domain. As a result, privileges cannot be set on the domain controller and granted
to all computers on the domain.
CAUTION:
Enabling the option, Allow service to interact with desktop when running
Sterling Connect:Direct under the local System account, presents a security risk
and may allow access to services that interact with the desktop.
After you create the account, you assign it as the account for Sterling
Connect:Direct. To identify the custom logon account:
Procedure
1. Select Start > Settings > Control Panel > Administrative Tools > Services.
2. Double-click the Sterling Connect:Direct server.
3. Click the Log On tab.
14 Sterling Connect:Direct for Microsoft Windows 4.7: Documentation
4. Select This account to identify the custom logon account.
5. Type the account name to use for logging onto Sterling Connect:Direct, or click
Browse and double-click the user account.
6. Type the password in the Password and Confirm password fields.
7. Click OK.
In addition, create an active connection between the local and remote nodes.
Sterling Connect:Direct for Microsoft Windows requires the following information
for the local and remote SNA networks in order to configure a peer- or host-based
partner SNA connection:
v Network name
v Mode name (local system only)
v Control point name
v Node ID
v Network address (remote system only)
v LU name and LU alias name (these names may be the same value; Sterling
Connect:Direct uses the LU alias name)
Note: Consult the SNA product documentation or contact your SNA vendor for
any questions about configuring the SNA communications software.
v LU Name
v Network Name
v Control Point Name
v Node ID
v Network Address
***************************************************
* *
* *
*XCA TR DEFINITION *
* *
* *
*CHANGE LOG *
* *
***************************************************
M1R01PU VBUILD TYPE=SWNET, X
MAXGRP=1, MAXIMUM NUMBER OF UNIQUE GRPNM X
MAXNO=1 MAXIMUM NUMBER OF UNIQUE DIALNO
*
***
M1RPU01 PU ADDR=01, X
PUTYPE=2, X
ISTATUS=ACTIVE, X
DBLK=071, X
IDNUM=6200D, X
PASSLIM=8, X
DLOGMOD=NDM624K, X
MODETAB=DALLMTAB, X
SSCPFM=USSSCS, X
USSTAB=LSUSSTAB, X
PACING=7, X
VPACING=7, X
DISCNT=(NO), X
MAXDATA=521, X
MAXPATH=2, X
MAXOUT=8
*
M1RPTH0D PATH GRPNM=M1XG516D, X
DIALNO=0011111111111D DUMMY
*M1ROLUA LU LOCADDR=0, DLOGMODE=NDM6241C
*3270
*
M1R01LU2 LU LOCADDR=2,DLOGMOD=D4A3290
M1R01LU3 LU LOCADDR=3,DLOGMOD=D4A3290
*
*LU 6.2 ILU
*
******************************************************************
VTAM 3.4 CDRSC DEFINITIONS FOR INDEPENDENT LU’S *
* 6.2 ILU DEFINITION - XCA TR ACCESS *
*CHANGE LOG: *
* *
* *
* *
******************************************************************
M1R01CDS VBUILD TYPE=CDRSC
*
M1R01CDS VBUILD TYPE=CDRSC
ALSLIST=M1RPU01, ADJ LINK STATION X
MODETAB=DALLMTAB, LOGON MODE TABLE X
DLOGMOD=NDM624K, LOGON MODE TABLE ENTRY X
RESSCB=5 SESSION CONTROL BLOCKS
M1R01LUB CDRSC ISTATUS=ACTIVE, X
ALSLIST=M1RPU01, ADJ LINK STATION X
MODETAB=DALLMTAB, LOGON MODE TABLE X
DLOGMOD=NDM624K, LOGON MODE TABLE ENTRY X
RESSCB=5 SESSION CONTROL BLOCKS
*
M1R01LUB CDRSC ISTATUS=ACTIVE, X
ALSLIST=M1RPU01, ADJ LINK STATION X
MODETAB=DALLMTAB, LOGON MODE TABLE X
DLOGMOD=NDM624K, LOGON MODE TABLE ENTRY X
RESSCB=5 SESSION CONTROL BLOCKS
*
M1R01LUC CDRSC ISTATUS=ACTIVE, X
ALSLIST=M1RPU01, ADJ LINK STATION X
MODETAB=DALLMTAB, LOGON MODE TABLE X
DLOGMOD=NDM622K, LOGON MODE TABLE ENTRY X
RESSCB=5 SESSION CONTROL BLOCKS
*
M1R01LUD CDRSC ISTATUS=ACTIVE, X
ALSLIST=M1RPU01, ADJ LINK STATION X
MODETAB=DALLMTAB, LOGON MODE TABLE X
DLOGMOD=NDM621K, LOGON MODE TABLE ENTRY X
RESSCB=5 SESSION CONTROL BLOCKS
*
*****************************************************************
* *
* XCA MAJOR NODE *
* *
* CHANGE LOG: *
*****************************************************************
M1XCA516 VBUILD TYPE=XCA XCA MAJOR NODE
*
M1XP5161 PORT MEDIUM=RING, TOKEN-RING X
SAPADDR=4, SERVICE ACCESS POINT ADDRESS X
ADAPNO=0, ADAPTER NUMBER X
CUADDR=516 CHANNEL UNIT ADDRESS
*
M1XG516D GROUP DIAL=YES, SWITCHED PERIPHERAL NODE X
CALL=IN, DIAL IN AS PER MCDATA X
ISTATUS=ACTIVE ACTIVATED AT GEN
*
M1XL516D LINE ANSWER=ON PU CAN DIAL IN
*
M1X516PD PU
*
***
LOCALNODE= ADJACENT.NODE=(
(node name[b], (node name[a],
communications name[o],, communications name[m],,
superuser password) LU62)
TCQ=(tcxdsn, tcqdsn)) PARSESS=(max[d], default)
ENVIRONMENT=NT
LOGMODE=logmode entry name[c])
snacfg /print>filename
The following sample illustrates the Microsoft SNA server configuration listing for
a configured Microsoft Windows server using the values listed in the VTAM
Sample Definitions:
For each parameter listed, record the parameter value mapped between SNA and
VTAM. Use the alphabetic identifier to understand how the parameters are
implemented in the network map in the example.
Note: When installing in a clustered environment, you must deselect the Requester
feature (do not install it at this time). Instead, do one of the following:
v Install the Sterling Connect:Direct Requester (Stand-Alone) using the
CDRequester Setup.exe. See Installation Notes for Sterling Connect:Direct
Requestor for more information.
v Install the Requester feature on a different system outside the cluster
environment.
Installation Overview
After you complete the installation worksheets, you are ready to install Sterling
Connect:Direct for Microsoft Windows.
Additionally, if you have a large network of computers where you need to install
Sterling Connect:Direct for Microsoft Windows, you can set up a silent installation.
To configure a silent installation, install Sterling Connect:Direct for Microsoft
Windows at one computer. Then use the initialization parameters file that was
created during the installation to create a silent installation. Send the modified INI
file to each computer on which to perform the silent installation.
Icons are displayed by each component to illustrate the selected installation type.
The icons and installation types are described below:
Procedure
1. If you are installing from a CD, insert the CD into the CD drive. If Autorun is
enabled, the installation automatically starts. Otherwise, start setup.exe from
the Microsoft Windows run option.
2. If you downloaded the software, double-click setup.exe from the download
folder.
3. On the Welcome dialog, click Next.
4. To install Sterling Connect:Direct Secure Plus or SNMP, select Custom and
click Next. The Custom Setup dialog box is displayed that shows the features
available for installation.
v To configure MySQL or SQL Server, disable the solidDB feature on this
dialog.
v To install Sterling Connect:Direct Secure Plus, click the icon next to
application and identify the type of installation.
v To install an SNMP extension agent, click the icon next to the application to
remove the red X. This option is only available if SNMP Trap Service is
installed.
Note: If you chose another database and decide to install solidDB at a later
time, run setup.exe. You can also install the solidDB feature using the
"Add/Remove Programs" tool from the Windows Control Panel, or
"Programs and Features" on Windows Vista and later Windows versions. .
v To configure MySQL, type the MySQL Server options provided by your
system administrator and click Next.
If you chose a database other than the included solidDB, make sure you have
installed your database before you begin this installation.
Procedure
1. Insert the CD into the CD drive. If Autorun is enabled, the installation
automatically starts. Otherwise, start setup.exe from the Microsoft Windows
run option.
2. If you downloaded the software, double-click CDWindows setup.exe from the
download folder.
3. On the Welcome dialog, click Next.
4. Select Typical and click Next.
Note: The SQL Server option applies to either a remote SQL Server or the
local installation of SQL Server Express.
7. Click Next.
8. Configure the database you selected as follows:
v If you accepted the default database, solidDB, type the information
provided by your system administrator and click Next.
Note: If you chose another database and decide to install solidDB at a later
time, run setup.exe. You can also install the solidDB feature using the
"Add/Remove Programs" tool from the Windows Control Panel, or
"Programs and Features" on Windows Vista, 2008R2 or Windows 7.
v To configure MySQL, type the MySQL Server options provided by your
system administrator and click Next.
v To configure SQL Server, type the address of the remote SQL Server and
identify the authentication method. Click Next.
v For SQL Server Express, the SQL Server field is populated with
(local)\CDWINDOWS. Unless an advanced configuration is performed, do
not make changes to the SQL Server field or the Microsoft Windows
authentication credentials of the current user. Click Next.
9. Click Install.
10. When the installation is finished, Sterling Connect:Direct Requester is
automatically started. If you do not want it to start automatically, deselect the
option.
11. Click Finish.
32 Sterling Connect:Direct for Microsoft Windows 4.7: Documentation
Upgrade Sterling Connect:Direct for Microsoft Windows
About this task
Procedure
1. Double-click the setup.exe file.
2. On the Welcome dialog, click Next.
3. To install Sterling Connect:Direct Server and Requester, select Typical. Click
Next.
4. To install Sterling Connect:Direct Secure Plus and Sterling Connect:Direct for
Microsoft Windows, select Custom. Click Next.
5. Select Upgrade and click Next.
6. To save the previous version of Sterling Connect:Direct, check Keep <version -
nodename>." Click Next.
7. Click Install.
8. If you installed Sterling Connect:Direct Requester, it starts automatically. To
disable the automatic start, deselect this option. Click Finish.
Before you can add a component, Sterling Connect:Direct for Microsoft Windows
must be installed.
After you install the product, you can change the installed components including
repair a component that is corrupt, remove a component, or install an additional
component.
Procedure
1. Start the Sterling Connect:Direct for Microsoft Windows installation.
2. On the Welcome dialog, click Next.
3. To install additional components:
a. Select Modify and click Next.
b. Select the component to add and enable This feature will be installed on
local hard drive. Click Next.
c. Click Install.
d. Click Finish.
Procedure
1. Start the Sterling Connect:Direct for Microsoft Windows installation.
2. On the Welcome dialog, click Next.
3. Select Repair and click Next
4. Click Install to repair the installation.
5. Click Finish to complete the modification.
Procedure
1. Start the Sterling Connect:Direct for Microsoft Windows installation.
2. On the Welcome dialog, click Next.
3. Select Modify to remove a Sterling Connect:Direct component and click Next.
4. Select the component to remove, select This feature will not be available, and
click Next.
5. Click Install.
6. Click Finish.
Computers other than the one on which Sterling Connect:Direct is installed may
require that Sterling Connect:Direct Requester be installed.
Procedure
1. Insert the Sterling Connect:Direct Requester CD into the CD drive or
double-click the CDRequester setup.exe file downloaded from IBM Passport
Advantage.
When you install Sterling Connect:Direct File Agent, Java Runtime Environment
(JRE) is automatically installed.
Procedure
1. Insert the Sterling Connect:Direct for Microsoft Windows CD into the CD drive,
or locate the files you extracted from the IBM Passport Advantage, and
double-click the FileAgentInstall.exe file.
2. From the Introduction dialog box, click Next.
3. To install Sterling Connect:Direct File Agent in a selected location, click Choose
and select the location.
4. Click Next, then click Install.
5. When the installation is complete, click Done.
The Sterling Connect:Direct for Microsoft Windows Uninstall program removes the
application, its components, Sterling Connect:Direct Requester, and Sterling
Connect:Direct for Microsoft Windows server, program items, and most server and
Registry settings.
To uninstall the Sterling Connect:Direct Server program and all of the server
utilities:
Procedure
1. Click Start > Programs > Settings > Control Panel > Add-Remove Programs.
2. Highlight Sterling Connect:Direct for Microsoft Windows and click Remove.
3. Click Yes to confirm the removal of this program.
4. Click Finish.
5. Click OK to close the Add/Remove Programs Properties dialog box.
If you communicate with a trading partner using a firewall, set two initialization
parameters to support it. You assign a specific TCP/IP source port number or a
range of port numbers with a particular TCP/IP address or addresses for outgoing
Procedure
1. Coordinate IP addresses and associated port assignments with your firewall
administrator.
2. Add the following parameter to the Local Node Characteristics section of the
initialization parameters file: tcp.src.ports=(valid IP address/optional subnet
mask | valid IP address pattern, associated port number | associated range of
port numbers | associated port number, associated range of port numbers)
3. Apply the new initialization parameter.
4. A second parameter called tcp.src.ports.list.iterations is automatically added to
the Local Node Characteristics section during installation and has a default
value of 1. Refer to the following table for a description and valid values for
these parameters:
(199.2.4.*, 1024),
(fd00:0:0:2015:*::*, 2000-3000),
(199.2.4.0/255.255.255.0,
4000-5000),(fd00:0:0:2015::0/
48, 6000, 7000)
A session to 200.200.4.10 uses a port from within the two ranges specified (2000 to
2100 or 3000 to 3100). Additionally, because of the subnet mask specification, a
session to any IP address beginning with 200.200 will choose a port from within
the two ranges specified.
The port for a session to any address beginning with 138.16.17 is selected from one
of the two ranges (2000 to 2050 or 3000 to 3050) or the two individual ports
specified (4001 or 4005).
Automate Installation
You can perform a default silent installation that installs Sterling Connect:Direct
server and Sterling Connect:Direct Requester, or you can use transforms to modify
the settings of an installation package. The transforms included with this product
enable, disable, and remove a feature from the Sterling Connect:Direct for
Microsoft Windows.msi package. To change the silent installation setting, use a
transform to enable or disable the desired feature.
For each node where a silent installation is performed, determine if the node uses
special services, for example, Active Directory, SNMP, or SNA. For these nodes, a
custom INI file is required. If no custom INI file is present, the default installation
is performed.
The Sterling Connect:Direct server supports an INI file, which can specify the
value of installation properties. If you plan to use the INI file to manage a silent
installation, change the parameters of the INI file provided with Sterling
Connect:Direct for Microsoft Windows to specify site-specific information.
To define site-specific parameter values in an INI file for each node where you
install Sterling Connect:Direct for Microsoft Windows using the silent installation,
do the following:
Procedure
1. Open the CD_SRVR.INI file using any text editor, such as Microsoft Windows
Notepad.
2. Define the site-specific initialization parameters for a node and save the file.
3. Repeat steps 1–2 for each server where Sterling Connect:Direct will be installed.
Setup.exe installs the Microsoft Installer, Visual C++ Runtime Libraries and other
prerequisites on a system when they do not already exist. To complete the
installation, Setup.exe reboots the system if required and resumes the installation
after the computer has restarted.
To attach to the network and install Sterling Connect:Direct for Microsoft Windows
features from the network location in a silent installation:
Procedure
1. Click Start > Run. The Run dialog box is displayed.
Setup.exe /s /v/qn
Setup.exe /x
You can configure the local node using the Configuration Tool or with Sterling
Connect:Direct Requester. This set of topics provides instructions for using
Requester. Requester is a graphical user interface that enables you to define local
nodes, user IDs, user authorities, and remote user proxies.
With the Sterling Connect:Direct Configuration Tool, you edit text files of user
authorization and network map parameters, and you can export these files.
However, using the Configuration Tool requires that you understand all the
Sterling Connect:Direct keywords and their parameters. Sterling Connect:Direct
Requester makes it easier to define user authorization parameters.
Note: The Configuration Tool also enables you to view or print a configuration.
See Print and View Node and Network Map Definitions under Define and Manage
the Sterling Connect:Direct Network.
Procedure
1. Select Node > Connection Settings > Insert Node.
2. Type the node name in the Name field or select a node in Active Directory
Nodes if Active Directory is enabled.
3. Optionally, select the default user ID to associate with the node in the Default
User ID field.
4. Select the operating system used by the node in the Operating System field. If
any nodes are registered in Active Directory, select Windows to display nodes
registered in the Active Directory Nodes field.
Note: See “Specify IP Addresses, Host Names, and Ports” on page 147.
6. Type the port number in the Port field.
7. If this is the default node, select Set as the Default Node.
8. Click OK.
9. To modify a local node definition for a server at your site, double-click the
node on the Nodes tab of the Control Pad (left side of the Requester main
window). Modify fields as required and click OK.
Adding a User
About this task
To add a new Sterling Connect:Direct user from Sterling Connect:Direct Requester:
Procedure
1. If more than one local node is configured, on the Nodes tab of the Control Pad,
highlight the local node to which the user is to be added.
2. Select Node > Connection Settings > Edit Userids.
3. Click Insert.
4. Type information in the following fields:
v 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 "[email protected]".
v Password—Type the password defined for the user.
v Verify Password—Retype the password defined for the user.
5. Click Remember Password to automatically reload the password when you
attach as this user.
6. Click Set as the Default User if you want the new user to be the default user
for the node.
7. Click OK.
8. If the verification password you typed does not match the initial password, you
receive a message indicating the passwords do not match when you click OK.
Retype the verification password and click OK.
9. Click OK on the User Properties window to save the settings, then click Close.
Attention: Changes made to node settings are not written to the Registry until
you select OK.
Modifying a User ID
About this task
Procedure
1. If more than one local node is configured, on the Nodes tab of the Control Pad,
highlight the local node for which the user is to be modified.
2. Select Node > Connection Settings > Edit Userids.
3. Double-click the user ID to modify.
Deleting a User
About this task
Procedure
1. If more than one local node is configured, on the Nodes tab of the Control Pad,
highlight the local node from which the user is to be deleted.
2. Select Node > Connection Settings > Edit Userids.
3. Select the user you want to delete.
4. Select Delete, then click Confirm. The user is deleted.
After you configure the local node and define network users, you must attach to
the local node. If a user ID is set as the default and has the option Remember
Password activated, the user is automatically attached to the server.
Procedure
1. Select Node > Attach.
2. Select a user ID from the Userid list.
3. In the Password field, type the password that corresponds to the user ID.
4. Click OK.
You can define two types of users: administrators and general users. Each user
type has a set of default privileges. The default administrator and general user
definitions allow the user to perform basic Sterling Connect:Direct tasks. You can
use these templates to assign user authorities and restrict privileges. The following
table defines the default authorities of the administrator and the general user:
You then define directories where a user can perform tasks. If you do not specify a
directory for a function, the user can perform it from any directory, regardless of
whether the request is submitted from the PNODE or the SNODE; however, the
remote user proxy can override the directory specification. Directory restrictions for
the Upload and Download directory can be bypassed if restrictions are not also
provided for the Process and Program directory paths. As a result, if the remote
user is allowed to use the Run Task and Run Job features to execute commands
from any directory, then they could perform operating system commands. These
commands could include copy commands to copy files to any directory, bypassing
the Upload and Download restrictions.
To prevent this, set directory restrictions for the Process and program features
using a separate directory path from the Upload and Download directory path or
disable the Run Job and Run Task for this user. Programs that be run are defined
in the Process and Program directories.
You can define remote user proxies. A remote user proxy associates a remote user
with a local user ID and gives the remote user the authority to perform the same
functions as the proxy. This is useful if you want to give a remote user access to a
server, but you do not want to define a user ID and user authorities for the user.
Defining a remote user proxy also provides the remote user access to the local
node without the need to remember password information.
Use this procedure to restrict the functions that a user can perform and the
directories where a function can be performed.
Procedure
1. Select Admin > Functional Authorities. The User Authorities view is the
default view.
2. Choose one of the following types of users:
v Click New Admin to create a new user authority with full privileges for
Process controls and functions.
v Click New Genusr to create a user authority with reduced privileges.
3. Type a name, from 1 to 50 alphanumeric characters, for the new user in the
Name field. You can use spaces.
Procedure
1. Select Admin > Functional Authorities.
2. Double-click the user authority to edit.
3. Change the user authorities as necessary.
Procedure
1. Select Admin > Functional Authorities.
2. Select the user you want to delete and click Delete.
Use this procedure to create group authorities. Group authorities allow you to
group users who exercise the same level of functional authorities.
Procedure
1. Select Admin > Functional Authorities.
2. Click the Group Authorities tab.
3. To add a group authority, do one of the following:
v Click New Admin to create a new group based on *Admin settings as the
default.
v Click New Genusr to create a new group based on Genusr settings as the
default.
4. Type the name, from 1 to 50 alphanumeric characters, for the new group. You
can use spaces.
5. Define the group as either a local group or domain group by doing one of the
following:
v If the group is local, click Local and enter the name of the group as defined
by the workstation administrator under My Computer/Manage/Local Users
and Groups.
v If this is a domain group, click Domain Name, then enter the name of the
group as defined by the domain administrator, and the name of the domain
on which the group is defined.
Note: Local groups are groups defined locally on the server using the O/S
utility for managing local users and groups. If your users are defined locally,
use local groups. If your users are not defined locally but in a domain, use
domain groups. If you have some users in local and some in domains, you can
use both.
6. Do one of the following:
v To save the new group authority with default privileges, click OK.
v To modify the default group privileges, continue with the next step.
7. To restrict the control functions or statements users in the group are authorized
to perform, change the value of the fields on the available tab to No to deny
authority for that privilege and click OK.
Procedure
1. Select Admin > Functional Authorities and click the Group Authorities tab.
2. Double-click the group authority to edit.
3. Change authorities for the group as necessary.
4. Click OK.
A user can be a member of multiple groups, local and domain. Since each group
authority defined can contain different restrictions, the order of groups as they are
checked for a match is important. More restrictive groups should be checked
before less restrictive groups.
Procedure
1. On the Group Authorities tab of the Functional Authorities window, select the
group functional authority to move.
2. Move the group up in the order by clicking Move Up.
3. Move the group down in the order by clicking Move Down.
4. Click OK.
Procedure
1. Select Admin > Functional Authorities and click the Group Authorities tab.
2. Select the group you want to delete and click Delete.
Sterling Connect:Direct names each definition of this type according to the remote
node and submitter ID. Each definition contains the user ID and password for a
local account to use when the specified remote user submits Processes that interact
with this node.
Note: When you update the password for the specified local user account on your
Microsoft Windows system, you must update the corresponding Sterling
Connect:Direct secure point-of-entry proxy as well. This process is not automated.
The user proxy definition specifies the following Sterling Connect:Direct remote
user information:
v Remote Sterling Connect:Direct user ID and remote Sterling Connect:Direct node
name. You can also set a generic user ID called <ANY USER> and node name
<ANY NODE> to allow all of your remote users to connect through one proxy.
v Local user ID and password to use with submitted operations from the remote
Sterling Connect:Direct node.
v Any directory restrictions for Sterling Connect:Direct operations.
When a remote user submits a Sterling Connect:Direct Process that does not have a
remote node security ID specified, Sterling Connect:Direct for Microsoft Windows
accesses the proxy definition that corresponds to the specified user and logs on to
the Microsoft Windows server using the account information specified in the proxy
definition. If a proxy definition is not available for a given remote node/submitter
ID combination, the Process must explicitly specify the user ID and password to
use on the local node. Use the remote node ID security parameter in the Process
statement to provide the necessary security information to execute Processes with
this node.
Procedure
1. Select Admin > User Proxies.
2. Do one of the following:
v To add a new remote user proxy, click Insert.
v To modify a proxy, double-click the Remote User name to modify.
3. Add or modify the following information:
a. For a new proxy, type the remote node user ID or select <ANY USER> to
define a generic user ID.
b. Type the submitter ID, a specific node name, or select <ANY NODE> to
define a generic node.
c. Type the local user ID to map to the remote node or a specific user ID in
the Userid field.
d. Type the password twice associated with the local user ID to which the
proxy is mapped.
Procedure
1. Select Admin > User Proxies.
2. Select the remote user you want to delete.
3. Click Delete.
4. Click Close.
The remote node definition, the communications mode, and communications path
definition are the three components of each network map entry.
Note: The network map is not mandatory if the initialization parameter called
netmap.check is set to n and all remote nodes have TCP/IP paths that you identify
by their IP address or host name.
The remote node definitions contain information for remote Sterling Connect:Direct
nodes that the local Sterling Connect:Direct node communicates with.
Procedure
1. Select Admin > Netmap to open the network map.
2. Do one of the following:
v To add a node, select Netmap > Insert and type a node name in the Name
field.
v To modify an existing node, double-click the node name in the Netmap
window.
3. Define information in the following fields for the remote node you are
configuring on the Main tab. Refer to the following table for information on
each field:
4. To configure TCP/IP settings, click the TCP/IP tab and set the TCP/IP
attributes. Refer to the following table for definitions of the fields:
Port/Service The communications port number for A numeric value in the format nnnnn, where
Sterling Connect:Direct if it differs from the nnnnn is a positive integer from 0–65535.
default value specified in the initialization
parameters.
Mode Override Select the name of the network map TCP/IP Name of a defined TCP/IP communications
communications mode definition record used mode.
when communicating with this remote node.
If this parameter is not specified, its value
defaults to the last TCP/IP mode in the list.
Alt Comm Outbound The alternate communication address Fully qualified host name or IP address and
(communication path) used for outbound port number.
Processes. This parameter provides the
alternate addresses for a remote node that A comma separates the list of alternate
has multiple NIC cards. When the local node communication paths as shown in the
is the PNODE, the alternate addresses are following example:
tried (starting with the first IP address listed)
if an initial attempt to the primary address salmon;9400, 10.20.40.65;9500
fails. After a connection has been established,
The list is processed from the top down.
if the connection is subsequently lost,
attempts to reestablish the connection
through the retry mechanism use the same
address as the initial connection.
5. To configure UDT settings, click the UDT tab and set the UDT attributes.
Refer to the following table for definitions of the fields:
6. To configure the APPC settings, click the APPC tab and set the APPC
attributes. Refer to the following table for a description of the fields:
You can add or modify the settings for a communications mode object. These
values override the values in the initialization parameters file.
Procedure
1. Select Admin > Netmap to open the network map.
2. Do one of the following:
v To modify an existing mode definition, double-click the mode.
v To add a new mode definition, right-click in the mode box and click Insert.
4. To add or update TCP/IP settings, click the TCP/IP tab. Refer to the following
table for a description of each field:
5. To add or update APPC settings, click the APPC tab and type the following
values:
a. A valid RU size between 256 and 4096 in the Max RU Size field. The
default is 4096.
The communications path defines the physical communications path between the
local Sterling Connect:Direct node and one or more remote Sterling Connect:Direct
nodes.
If you install SNA software and select APPC support during installation, two
communications path objects are created in the Microsoft Windows Registry: one
for TCP/IP and one for APPC. If you do not have APPC support, only a TCP/IP
default communications path object is created.
Procedure
1. Do one of the following:
v To modify a communications path definition, double-click the definition in
the CommPath window.
v To add a new communications path, right-click the CommPath box and click
Insert.
2. To define a communications path, type the name of the communications path
in the Name field, and select the protocol to associate with it: TCP/IP, APPC,
or UDT.
3. Define a new mode or assign an existing mode to the communications path.
4. To associate an existing mode with the communications path, select the mode
from the Selected Mode drop-down list.
5. To define a new mode to associate with the communications path:
v Click New.
v Type the name of the new mode in the Name field.
v Select the protocol to associate with the mode: TCP/IP, APPC, or UDT, and
click OK.
6. To add or update TCP/IP settings, click the TCP/IP tab. Refer to the following
table for the name, definition, and valid values for each field.
7. To add or update APPC settings, click the APPC tab. The following table shows
the name, definition, and valid values for each field on the APPC tab.
8. To add or update UDT settings, click the UDT tab. The following table shows
the name, definition, and valid values for each field on the UDT tab.
9. Click OK.
Procedure
1. Select Admin > Netmap to open the network map.
2. Right-click the CommPath box and click Insert.
3. Type the name of the communications path in the Name field.
4. Click New.
5. Type the name of the new mode in the Name field.
6. Select TCP/IP, APPC, or UDT to identify the protocol to associate with the
mode.
7. To add TCP/IP settings, click the TCP/IP tab. Refer to the following table for
the name, definition, and valid values for each field.
8. To add UDT settings, click the UDT tab. Refer to the following table for the
name, definition, and valid values for each field.
Procedure
1. Select Admin > Netmap.
2. Right-click the network map entry you want to delete and click Delete.
After you create a network map entry, you can validate the entry to ensure it was
created correctly. For example, if you typed an invalid entry in a field, or
accidentally deleted a communications path, the validation function generates an
error message and explains why you received it.
Procedure
1. Select Admin > Netmap.
2. Select the network map entry to validate.
3. Right-click the Netmap for Nodename window and click Validate.
4. After you validate the network map entry, close the Netmap for Nodename
window.
Procedure
1. Select Admin > Netmap.
2. Select the network map entry you want to view as text.
3. Right-click the Netmap for Nodename window to open the shortcut menu and
click Text View.
4. Right-click the window again and select List View to view the network map
entry in its original presentation.
Procedure
1. Select Admin > Netmap > Validate. If no errors are found, the output window
contains the message Netmap validation Successful.
2. Select Netmap > Apply.
3. Select the node name and click OK.
After you set up a node and define a network map, use the Configuration Tool to
extract the network map and user authorization information from the Registry as
plain text files. You can then update the parameters in the extracted files for
distribution to the nodes in an environment.
After you customize the files with site-specific parameters, you can insert them
into the Microsoft Windows Registry where they are applied while the server is
running, or you can apply them during a new Sterling Connect:Direct installation.
Procedure
1. Click Start and point to All Programs > IBM Sterling Connect:Direct > v4.6.0
> CD Configuration Tool.
2. Select File > Extract.
3. Click OK. The network map and User Authorization information for the node
are extracted as cascading windows named Map and User.
4. To save the extracted user authorization information:
a. Click the User dialog box.
b. Select File > Save As.
c. Select the directory where you want to save the file.
d. If necessary, type a different file name in the File name field and click Save.
5. To save the extracted network map information:
a. Click the Map dialog box.
b. Select File > Save As.
c. Select the directory where you want to save the file.
d. If necessary, type a different file name in the File name field and click Save.
Two sample configuration files are included with the Configuration Tool:
v Map.cfg file—Network map objects are created in the Registry during
installation. These objects contain the remote node, communications path, and
communications mode definitions. You can update the network map on your
nodes by customizing the sample Map.cfg file and inserting it into the Microsoft
Windows Registry.
v User.cfg file—Use the parameters in User.cfg to build user functional authorities
and user proxies. Sterling Connect:Direct applies the information in this file to
authorize local and remote users to issue commands and Process statements and
to perform tasks. Use the Configuration Tool to create authorizations for each
68 Sterling Connect:Direct for Microsoft Windows 4.7: Documentation
user, including encrypted passwords for user proxies. After you have created the
user authorizations, you can insert the User.cfg file into the Microsoft Windows
Registry.
You use the Configuration Utility to customize configuration files for your
environment and prepare them for rollout. You can edit configuration information
using this tool. You can also use it to add encrypted passwords to user proxies and
validate the configuration files for use with Sterling Connect:Direct.
Procedure
1. Select File > Open.
2. Select the drive and directory where the configuration file is located.
3. Select the file and click Open.
Note: To save the original file as a template for building future configuration
files, save the file with a different name before you alter any of the
configuration information.
4. Edit the parameters as necessary.
5. Select File > Save.
The Configuration Utility can be used to insert encrypted passwords into the proxy
section of the USER.CFG file. When you enter a password, the Configuration
Utility encrypts it for you.
Procedure
1. Open the User.cfg file.
2. Place the cursor on the line following the Proxy section header.
3. Select Tools > Password.
4. Type the user ID and password in the Userid and Password fields.
5. Retype the password in the Verify Password field.
6. Click OK. The encrypted password is inserted as the LocalPassword parameter
value and the User ID is inserted as the LocalUserid parameter.
After you have customized a file, validate the configuration to ensure that the file
can be used with Sterling Connect:Direct. When you validate a file, error messages
describe any errors and each error is highlighted so you can easily determine
which information must be revised.
Procedure
1. Open the configuration file to validate.
2. Select Tools > Validate. The file is validated.
v If no errors are detected, a message indicating this is displayed. Click OK to
return to the file.
v If errors are detected, an error message is displayed with the error identifier
and an explanation of the problem. The error is highlighted in the
configuration file. Click OK to close the error message.
3. Edit the configuration information to clear each error.
4. Repeat this procedure until no errors are returned.
You can update the network map and user authorizations, including proxies and
group authorizations, by adding the updated configuration files to the Microsoft
Windows Registry. After they are added, the settings are applied when the server
is running.
Restriction: You cannot use CDConfig to change existing objects in the network
map and user authorizations. It can only be used to create new netmap or user
authorization objects; however, you can use CDConfig to change individual
initialization parameters.
To create and apply user and netmap files in silent mode, type the following
commands:
EXTRACT CONFIGURATION
1. To extract initialization parameters to a Initparms.cfg file:
CDConfig.exe /pC:\MyDir\Initparms.cfg /q
2. To extract a netmap to a Map.cfg file:
CDConfig.exe /mC:\MyDir\Map.cfg /q
3. To extract user configuration to a User.cfg file:
CDConfig.exe /uC:\MyDir\User.cfg /q
INSERT CONFIGURATION
1. To update (individual) initialization parameters from an Initparms.cfg file:
CDConfig.exe /i /fC:\MyDir\Initparms.cfg /q
2. To insert new netmap objects from a Map.cfg file:
CDConfig.exe /i /fC:\MyDir\Map.cfg /q
3. To insert new user authorization objects from a User.cfg file:
CDConfig.exe /i /fC:\MyDir\User.cfg /q
Procedure
1. Select Admin > Netmap to open the node you want to stop.
2. Select Admin > Stop Node.
3. Select one of the stop server options:
Procedure
1. Click Start > Settings > Control Panel >Administrative Tools > Services.
2. Select the Sterling Connect:Direct node you want to stop.
3. Click Stop. The display changes to indicate that Sterling Connect:Direct has
stopped.
Note: Sterling Connect:Direct for Microsoft Windows does not implement the
Pause and Continue functions on the Services applet.
To stop Sterling Connect:Direct for Microsoft Windows from the CLI, issue the stop
command.
To stop Sterling Connect:Direct for Microsoft Windows from the Admin Tool
Utility:
Procedure
1. Select the Sterling Connect:Direct for Microsoft Windows server to stop.
2. Click the red traffic light icon on the toolbar.
About Processes
A Process is a set of statements grouped together to perform a series of Sterling
Connect:Direct tasks. You define the tasks to perform and save the Process to a file.
Finally, you use the Submit Process command to execute all the tasks defined in
the Process.
Processes allow you to automate routine tasks, execute multiple tasks with one
command, save the Process to a file for future use, and build blocks of work based
on conditions. Before you build a Process, decide what tasks you want to perform
and what nodes you want to use.
Before creating a Process, you can establish preferences related to Processes and
other Sterling Connect:Direct Requester operations.
Establishing Preferences
About this task
Throughout your session with Sterling Connect:Direct Requester, certain predefined
preferences are in effect. Sterling Connect:Direct establishes default user
preferences during installation. You can modify preferences at any time to more
accurately reflect how you work. Preferences save you time, since preferences are
used for all instances, except when you override the values.
To establish preferences:
Procedure
1. From the Sterling Connect:Direct Requester Main Window, select Tools >
Options.
2. To set general preferences, change the values in the fields on the General tab of
the Options panel.
Field Description
Reload last saved workspace at startup When selected, Sterling Connect:Direct Requester displays the last
saved workspace when you log in.
Track Processes in the execution status To obtain summary information about a Process and display the
window information in the Execution Status Window. This option establishes
the default for the Submit Process page.
Enable in-place editing To directly change the label field on the Program Definition Editor
(PDE) and eliminate the need to edit the labels through the Process
Properties page.
Check Enable the activity log in the Output window to display the
activity log there.
Check Write the activity output to a file and type the name of the
file to write the activity log to a file. Select the appropriate button to
create a new file every time you start Sterling Connect:Direct
Requester or to append activity to the existing log file at startup.
3. To set Process preferences, click the Process Defaults tab and change the values.
4. To set Work List preferences, click the Work List tab and change the values.
5. To set directory preferences, click the Directories tab and change the values.
Field Description
Processes To define the default directory for Process files
Work Lists To define the default directory for Work Lists.
Process Monitors To define the default directory for Process Monitor files.
Statistics Monitors To define the default directory for Statistics Monitors.
Start "Save as" in these directories Select this check box to make these directories the default when saving.
6. To set file type preferences, click the File Types tab and select the file extensions
to associate with Sterling Connect:Direct.
7. To set statistics preferences, click Select Stat Defaults and change the values.
8. To set Process Monitor preferences, click Select Proc Defaults and change the
values.
9. Click OK.
Creating a Process
About this task
A Process begins with a Process statement that defines general information about
the Process. When you create a Process, the PEND statement is added to the end of
the Process and is a required statement that marks the end of a Process. Do not
edit or delete the PEND statement.
Procedure
1. Select File > New > Process.
2. Type a Process name, from 1 to 8 alphanumeric characters, in the Process
Name field.
3. If all work will be performed on the PNODE, type or select the name of the
PNODE in the PNODE Name field.
4. To issue a warning message if an attempt is made to submit the Process on a
different PNODE, click Warn if submitted to a different node.
5. To issue a warning message if an attempt is made to submit the Process on a
PNODE with a different operating system, click Warn if submitted to a
different operating system.
6. Specify the SNODE in one of the following ways:
v Select the node from the drop-down menu.
v Type the name of a Sterling Connect:Direct node.
v Specify an IP address and port, using the following format:
hostname|IPaddress;portnumber|servicename
7. Click OK.
8. Add commands as necessary to the Process.
9. If desired, change the options for the Process.
The following table lists the commands you can insert in a Process.
Command Description
Copy The Copy statement transfers data between two nodes. The Copy statement identifies the
source files, applies any pre-transfer attributes such as compression or checkpointing, transfers
the file to the destination, and saves the file to the new file name.
Run Task You can run programs and commands by adding the Run Task command to a Process. The
Run Task command executes programs on the PNODE or the SNODE.
Run Job The Run Job command executes batch jobs or commands on the specified node. Jobs submitted
using the Run Job command run in the background. The return code associated with the run
job statement indicates the success of the Run Job command and not the success of the batch
job or command.
Use the Run Job command to perform the following types of tasks:
v Submit jobs in an z/OS environment to the internal reader, a facility that transfers jobs to the
job entry subsystem (JES).
v Submit a job at the OpenVMS node in an OpenVMS environment.
v Submit an OS/400 CL command to run as a separate job through the SBMJOB command.
v Invoke a UNIX command shell and execute UNIX commands.
v Submit jobs through the VSE virtual reader, a facility that transfers jobs to VSE/POWER.
v Start programs in the Microsoft Windows environment.
Submit Process Submits a Process from within an executing Process on the PNODE or the SNODE. To use the
Submit statement, the Process must reside on the node you are submitting the Process to. Use
the Submit statement to execute a Process on the SNODE which would, in turn, submit a
Process to a third node.
You can use the following conditional statements to perform tasks based on
conditions you establish.
Statement Description
If The If statement executes a block of statements based on the results of a previous statement. The
results are categorized by a return code. The If statement checks the value of the return code and
executes the block if the statement is true.
You must use the Eif statement (endif) with the If statement. If the conditions of the If statement
are not satisfied, use an Else statement to designate the execution of alternate instructions.
Else The Else statement defines a block of statements that execute when the If statement is not true.
The Else statement is only valid when used in combination with the If statement.
Endif (Eif) The Endif statement (Eif) marks the end of the If statement and any statements based on the If
condition. The Endif statement is only valid when used in combination with the If statement.
Goto The Goto statement executes a jump to a specific statement that occurs later in a Process. This
statement cannot be used to loop to a statement earlier in the Process. Use the Goto statement
with the step label to define the location of the statement in the Process.
Exit The Exit statement bypasses all remaining steps in a Process and ends the Process.
Use the Copy statement to create a new file or append data to an existing file. To
use the Copy statement in a Process, identify the PNODE and the SNODE. Identify
the source file and, if symbolic variables are used, assign values to the variables or
specify built-in variables before the Process is submitted.
Sterling Connect:Direct for Microsoft Windows supports the string (*) and
character (?) wildcards, allowing you to copy multiple files from a source directory
to a target directory with a single copy statement.
Note: The list of files to be copied is generated at the start of a wildcard copy.
When a Process restarts, in a wildcard copy statement, the step restarts with the
first file that is not completely copied. If you are using checkpointing, the
statement restarts at the last checkpoint of the file that is not completely copied.
Procedure
1. Open a Process file.
2. Select Process > Insert > Copy.
3. To identify the step within the Process, type a label of up to 8 alphanumeric
characters in Copy Statement Label.
4. Select one of the following actions:
v To copy a file to the SNODE, select Send.
v To copy a file from the SNODE, select Receive.
5. Type the name of the source file in the Source Filename field.
6. Enter the name of the file in the Destination Filename field.
7. Select one of the following destination disposition options:
v NEW—To create a new file at the destination
v RPL—To replace the information in an existing file if it exists or to create a
new file if the file does not already exist.
v MOD—To append the transferred information to an existing file.
8. To enter compression and checkpoint restart options, click the Transfer tab and
select from the following options:
v To use compression, select one of the following compression types in the
Compression window:
Note: These tabs reflect the operating system of the sending and receiving file
location.
10. Click the Comment tab and add an optional description of the statement.
11. Click OK.
You can run programs and commands by adding the Run Task statement to a
Process. The Run Task statement executes programs on the PNODE or the SNODE.
Procedure
1. Open a Process file.
2. Select Process > Insert > Run Task.
3. To identify the step within the Process, type a label of up to 8 alphanumeric
characters in Run Task Statement Label.
4. Select the node where the program or command will execute in the Submit To
field.
5. Type one of the following, based on the node type, in the Program field:
v Type Windows for a Microsoft Windows node.
v Type UNIX for a UNIX node.
v For OS/400, type cmd(CL command) [parameter for OS/400 SBMJOB
command] .
v For z/OS, type the name of the program to be attached as a subtask in
uppercase letters.
v For HP NonStop, type the name of the object file.
v For VSE, type the name of the program to be attached as a subtask in
uppercase letters.
6. Use the Optional Parameters or Commands as necessary, for the operating
system you selected in Step 5. Refer to the Help for syntax.
7. Click the Comment tab and add a description of the command. This
information is optional.
8. Click OK.
The Run Job command executes batch jobs or commands on the specified node.
Jobs submitted using the Run Job command run in the background. The return
code associated with the run job statement indicates the success of the Run Job
command and not the success of the batch job or command.
Procedure
1. Open a Process statement.
2. Select Process > Insert > Run Job.
3. Type the statement label in the Run Job Statement Label field.
4. Select the node where the job will execute.
5. Type the Filename based on the operating system used by the node. This field
is valid only for the following operating systems:
v For Microsoft Windows nodes, type Windows.
v For z/OS nodes, type the data set that contains the job in the format:
DATASETNAME | DATASETNAME(MEMBER). The data set and member
must be in uppercase. If the data set is a PDS, specify the member. The data
set containing the job must exist on the z/OS node where the job will
execute. A data set containing JCL is limited to a record length of 80 bytes.
v For i5 Series nodes, type i5 Series.
v For VSE nodes, type the name of the member in the LIBDEF source chain
that contains the job to be submitted in the format: | membertype(member).
If the membertype is not specified, this job must be cataloged with a
membertype of J.
v For UNIX, type dummy.
v For OpenVMS, type PGM=VMS.
6. Type any Optional Parameters or Commands.
7. Click OK.
Adding an If Statement
About this task
You must use the Eif statement (endif) with the If statement. If the conditions of
the If statement are not satisfied, use an Else statement to designate the execution
of alternate instructions.
Procedure
1. Select Process > Insert > If.
2. Enter the statement label in the If Statement Label field.
3. Select a step label on which to base the operator and value.
The Else statement defines a block of statements that execute when the If statement
is not true. The Else statement is only valid when used in combination with the If
statement.
Procedure
1. Select Process > Insert > Else.
2. Optionally, add a comment to the Process.
3. Click OK to save. The Else statement is displayed in the Process window.
The Endif statement (Eif) marks the end of the If statement and any statements
based on the If condition. The Endif statement is only valid when used in
combination with the If statement.
Procedure
1. Select Process > Insert > End If.
2. Optionally, type a comment for the Process.
3. Click OK to save. The Endif statement is displayed in the Process window.
The Goto statement executes a jump to a specific statement that occurs later in a
Process. This statement cannot be used to loop to a statement earlier in the Process.
Use the Goto statement with the step label to define the location of the statement
in the Process.
Procedure
1. Take one of the following actions:
v To create a new Goto statement, select Process > Insert > Goto and enter the
statement label in the Target Label field.
v To modify an existing statement, double-click the Goto statement in the
Process window.
2. To add or modify optional comments, click the Comments tab and type the
comment.
3. Click OK to save the Process. The Goto statement is displayed in the Process
window.
Procedure
1. Select Process > Insert > Exit.
2. Optionally, click the Comments tab and add a comment to the Process.
3. Click OK to save the Process and exit the Exit Statement dialog box. The Exit
statement is displayed in the Process window.
You can use one or more of the following options in a Process or command:
v Control functions identify how tasks are managed and how resources are
allocated by defining default options once. Then these values are used as the
default values for each new command or Process you define.
v Security options identify user IDs and passwords needed to access the SNODE
and the PNODE.
v Variable values assign values to all symbolic variables before execution. The
values are then substituted during execution whenever the symbolic variable is
encountered.
v Accounting data as a free-form, user-defined field sets up accounting and
tracking information about Process execution and data transfers. You can track
Use the Security options to specify the user IDs and passwords needed to access
the PNODE and the SNODE.
Procedure
1. Double-click the Process to open it and click the Security tab.
2. To set security for the PNODE, do the following:
a. Type the PNODE user ID in the PNODE Userid fields.
b. Type the PNODE password in the Password field.
3. To set security for the SNODE, do the following:
a. Type the SNODE user ID in the Snode Userid field.
b. Type the SNODE password in the Snode Password fields.
c. To change the password for the user ID on the SNODE, type the new
password in the New Password field.
d. Type the new password a second time in the Verify New Password field to
validate the change.
4. Click OK to close the dialog box or click one of the other tabs to continue
modifying Process options.
When you run a command or submit a Process, you can set many control
functions to use as the default values for each new command or Process you
define.
Procedure
1. Double-click the Process to open it and click the Control tab.
2. To specify a run date, select one of the following start dates:
v Today—If you want the program to run today.
v Date—To specify a date to run the Process. Click the selection arrow and
click a date on the calendar to specify the date.
v Day—If want to run the Process on a certain day; then select a day of the
week from the drop-down box.
3. To specify the time to run the task, select one of the following:
Note: If you select Yes for RETAIN and you specify a start time, HOLD status
takes precedence. If you set HOLD to No or Call, and set RETAIN to Yes,
HOLD is ignored.
6. If you are sending Processes to a location that supports CD Plexclass, type the
class value of the remote node, from 1 to 8 characters, in the Plexclass field.
7. In the CRC field, select one of the following options:
v Blank—To use the default value for the Process that was configured in the
Initparms and the Netmap entry for the remote node.
v OFF—To turn off CRC checking.
v ON—To turn on CRC checking.
8. To change the TCQ priority, type a value in the Priority field from 1 to 15,
where 15 is the highest priority.
9. To change the preferred session class, type the preferred session class in the
Class field, from 1 to the maximum local sessions defined in the network
map.
10. Type the user ID in the Notify Userid field.
11. Click OK to close the dialog box or click one of the other tabs to continue
modifying Process options.
Use symbolic variables to assign values to variables before execution. The values
are then substituted during execution whenever the symbolic variable is
encountered.
Procedure
1. Double-click the Process in the Requester and click the Accounting tab.
2. Type the information in the PNODE field to specify accounting data for the
PNODE. The maximum length of the string is 256 characters.
3. Type the information in the SNODE field to specify accounting data for the
SNODE. The maximum length of the string is 256 characters.
4. Click Reset to Defaults to reset to values specified in the Process Defaults page
of the Options dialog.
5. Click OK to close the dialog, or click one of the other tabs to continue
modifying Process options.
Add Comments
About this task
Procedure
1. In the Process window, select the statement about which you want to add
comments.
2. Select Process > Statement Properties.
3. Click the Comment tab.
4. Type the text in the Comment field.
5. Click OK to save the changes.
When you finish creating or modifying a Process, validate the content of the
Process.
Validating Process content checks the syntax for errors or missing information.
Validation does not check the content of the statements, only that they are
formatted correctly. The Process validation sends messages to the Output window.
A Validation Successful message means that the syntax is formatted correctly.
Procedure
1. Open the Process file.
2. Select Process > Validate.
3. View the messages displayed in the Output window. If messages indicate
invalid statements, edit the statements and validate the content of the Process
again.
Saving a Process
About this task
When you have finished creating or editing a Process, save the Process for future
use. Processes are stored in the Process directory.
Procedure
1. Select File > Save.
2. Type a name for the Process including the .CDP extension.
Copying a Process
About this task
You can use a Process as a template by copying the Process, making changes to the
copy, and saving the copy to a new Process file.
To copy a Process:
Procedure
1. Open the Process file.
2. Select File > Save As.
3. Save the Process with a new file name.
4. Change the Process statements. To change the Process statement, press Enter to
access the Process Properties dialog box.
5. To save the Process file with the changes, from the File menu, select Save.
Using Work Lists saves you time and effort by automating routine or repetitive
submission tasks. You can build a Work List to periodically submit related work as
a single work flow. Your Work List can serve as a library of related or unrelated
Processes.
Procedure
1. From the Sterling Connect:Direct Requester Main Window, select File > New >
Work List.
2. Add Work List items as desired.
3. To establish an automatic status monitor for the Work List as it executes,
perform the following actions:
a. Select WorkList > Work List Properties.
b. Activate Auto Monitor.
c. If you want the selected units of work to execute serially, turn on Serial
Execution. This feature causes the Submit action to wait until each unit of
work is completed before submitting the next unit of work in the Work List.
Processes are considered successfully completed if they do not have a status
of HI, PE, or EX.
4. To define substitution variables for the Work List, click the Variables tab. Select
one of the following actions:
v To add a new variable, type a name and value in the appropriate boxes and
click Add.
When you create a Process, a Send/Receive File Command, a Run Task Command,
or a Run Job Command, you can add the command to a Work List.
Use the Work List to define substitution variables, which you can set at submit
time. All the variables must have assigned or default values before the Work List is
submitted.
Procedure
1. Add a command.
2. Select Add to Worklist from the command you are creating.
Procedure
Once you create a Work List, perform one of the following actions.
v To submit all items in the Work List, select WorkList > Submit.
v Highlight the items to submit and select WorkList > Submit Selected.
When you submit a Work List or a task from the Work List, the Work List or task
is submitted to the TCQ. If you activate Auto Monitor, a Work List status window
displays the work items as they are submitted.
Although you cannot close a Work List until all of its tasks are executed, you can
cancel the execution of the tasks in a Work List.
You can edit the text of a Work List to change command statements.
CAUTION:
Editing the text of a Work List is a task for experienced users.
Procedure
1. Open the Work List that you want to edit.
2. Select Work List > Edit/View Text.
3. Edit the text as necessary using the following keyword and syntax rules. The
Work List Edit/View Text window enables you to see the full text of all tasks in
a Work List. You can edit the text directly if necessary. Put a keyword on a line
by itself.
Keyword Description
Set Work Task List
Submit Ad Hoc Process Task
Submit File= Submit Process Task
Run Local Program Task
4. Close the window. The program displays a message asking if you want to save
your work.
5. Click Yes. Your Work List is validated and saved. Any errors found during
validation are displayed at the bottom of your screen.
Procedure
1. Select Work List > Insert.
2. Select one of the following options to identify the task type to add to the Work
List:
v Submit from File
v Send/Receive
v Run Task
v Run Job
v Local Program
v Comment
3. Type any arguments in the box.
4. Enter the information for the Process in its dialog box.
5. Click OK. The Work List window is displayed.
Procedure
1. Open the Work List that you want to validate.
2. Select the tasks you want to validate.
3. Select Work List > Validate. The validation information is displayed at the
bottom of your screen.
Manage Processes
SMTP Notification
Sterling Connect:Direct uses the SMTP notification method and exchanges e-mail
using TCP/IP and a message transfer agent (MTA).
The SMTP standard is one of the most widely used upper layer protocols in the
Internet Protocol stack. This protocol defines how to transmit messages (mail)
between two users. SMTP uses spooling to allow mail to be sent from a local
application to the SMTP application, which stores the mail in some device or
memory. Once the mail has arrived at the spool, it is queued. A server checks to
see if any messages are available and then attempts to deliver them. If the user is
not available for delivery, the server tries later. Eventually, if the mail cannot be
delivered, it will be discarded or returned to the sender.
The initialization parameter tcq.start determines what the TCQ does with existing
Processes. The default value is tcq.start=w (warm start), which specifies that all
existing Processes in the TCQ are retained. A warm start restarts any Processes
submitted with the Process statement parameter retain=initial as well as any
Process that was executing in the TCQ when the server was brought down. You
can change the parameter to tcq.start=c (cold start) to delete all existing Processes
in the TCQ when the server restarts.
Each Process in the queue is assigned a status. The queues and status values are
identified in the following sections.
Execution Queue
Processes are placed in this queue after the connection to the SNODE occurs.
Processes typically come from the Wait queue, but also can be placed in the
Execution queue by a submit command with maxdelay= specified. After a Process
successfully finishes, it is automatically deleted from the Execution queue. When a
session is interrupted, the Process moves from the Execution queue to the Timer
queue, if retry values are specified. If connection is not made before the retry
values are exhausted or if retry values are not specified, the Process moves to the
Hold queue with a status of HE. The following table displays the status values
assigned in the Execution queue:
Status Comment
EX Process is executing between two Sterling Connect:Direct nodes.
PE Processes waiting for Process start messages to be exchanged between the
PNODE and the SNODE. This is the initial queue status when a Process is
submitted with maxdelay= specified.
Wait Queue
Processes are placed in the Wait queue while waiting for an available connection
between the PNODE and the SNODE. Processes can come to the Wait queue from
the Hold queue or the Timer queue. Processes also can be placed in the Wait queue
by a submit command with no parameters specified, submit with retain=no, or
submit with hold=no. After the connection is made, Processes automatically move
to the Execution queue. The following table displays the status values assigned in
the Wait queue:
Hold Queue
Processes are placed in this queue while waiting for operator intervention before
progressing to the Wait queue. This queue enables operators of the PNODE and
SNODE to coordinate and control Process execution.
Processes are placed in the Hold queue by a submit command with retain=initial,
retain=yes, or hold=yes parameters specified. Processes submitted with hold=call
also are placed in the Hold queue. Processes are moved from the Timer queue to
the Hold queue by a change process command with hold=yes specified. Processes
are moved from the Hold queue to the Execution queue by a change process
command with the release parameter specified.
The following table displays the status values assigned in the Hold queue:
Status Comment
HC The Process was submitted with hold=call specified. A session started from the
remote node causes the Process to be moved to the Wait queue in WC status.
The Process is placed in the Execution queue when the Process is selected for
execution.
HI The Process was submitted with hold=yes. The Process can be released later by
a change process command with release or hold=no specified.
HE A session error or other abnormal condition occurred.
HO A change process command with hold=yes was specified.
HR The Process was submitted with retain=yes or retain=initial specified and has
already executed. The Process can be released later by a change process
command with release specified.
HS The Process was suspended due to a server shutdown.
Timer Queue
Processes are placed in this queue by a submit command with the startt parameter
specified. Processes in the Wait for Start Time (WS) status are waiting for the start
time to arrive before moving to the Wait queue. Processes also are placed in the
Timer queue in Retry (WR) status after an error, such as a line break or a lost
connection. Sterling Connect:Direct automatically tries to execute the Process again
based on the number of times to retry and the delay between retries as specified in
the submit command, Process statement, network map parameters, or initialization
parameters. Processes move from the Timer queue to the Wait queue. A change
process command with hold=yes specified moves the specified Process from the
Timer queue to the Hold queue.
The following table displays the status values assigned in the Timer queue:
You can use more than one monitor to view different queues or to look at
Processes based on different criteria. You can arrange Process Monitors and save
the Workspace view so that when you enable that view, the Monitors are
automatically displayed. You can define how you want to display the Process
Monitor, what types of Processes you want to view, and what queues you want to
view.
Procedure
1. Select File > New > Process Monitor.
2. Do one of the following:
v To monitor all Processes, select All Processes.
v To monitor only those Processes that meet certain criteria, select Filter Using
Selection Criteria Pages. Define the criteria based on the options on the
remaining property pages.
v To refresh the monitor at specified intervals, select the Refresh every _
seconds option and enter the interval from 1-999 seconds.
v To monitor new data that was created since the Process Monitor was closed,
select Refresh on open.
3. Select the node on which to monitor Processes in the Node field.
4. Click OK.
Select the criteria to use to include in a Process Monitor. Select one or more of the
following filters: the status of a Process in the queue, the remote nodes included in
a Process, the user who submitted a Process, or a Process name or number.
Status Description
Execution Processes that are being serviced by the session manager.
Pending Execution The Process was submitted with the maximum delay option set
to zero.
Waiting Connection The Process is ready to execute as soon as a session is available.
Waiting Start Time The Process is waiting in the Timer Queue because it was
submitted with a start time or date that has not expired. When
the start time is reached, the Process is placed in the Wait queue
to schedule for execution.
Held Suspension The operator issued a delete process request with hold set to
Yes.
Timer Retry The Process is waiting for a retry attempt.
Held for Call The Process was submitted with the Hold option set to Call. A
session started from either node moves the Process to the Wait
queue in WC status. The Process is placed in the Execution
queue when the Process is selected for execution.
Held Due to Error A session error or other abnormal condition occurred.
Held Initially The Process was submitted with the Hold option set to Yes.
Held by Operator A change process request with hold set to Yes has been issued.
Held by Retain The Process was submitted with retention set to Yes or Initial.
Select All To monitor all status types.
Unselect All To deselect all status types.
Procedure
1. Select Files > Open.
2. From Files of Type, select Process Monitors (*.cdm) to display only Process
Monitor files.
3. Locate and select the Process Monitor file to open.
Saving a Process Monitor to a file lets you use the same format and monitor
criteria again. When you save a Process Monitor, you are saving the criteria and
the format of the Process Window; not the Process information displayed at the
time you save the monitor.
Procedure
1. Select File > Save.
2. Type the name of the Process monitor with the extension .cdm.
3. Click OK.
Field Content
Name Process name.
Number Process number.
Step Name Process step name currently executing.
Status Current status of the Process.
Queue Logical queue where the Process is currently located (Execution, Hold,
Wait, or Timer).
Byte Count Number of data bytes read or written.
0—Success
4—Warning
8—Error
16—Severe error
FDBK Feedback code.
Message Text Message short text.
Message Data The substitution variables with their values for the short text.
Log Date/Time The date and time the Process record was created.
Hold The hold status of the Process.
Class Session class on which the Process is executing.
Priority TCQ priority of the Process.
Local Node Indicates whether the local node is the SNODE or the PNODE in the
Process.
From Node Indicates whether the local or remote node is the FROM node in a
COPY.
Compression Compression factor used in a copy step
Checkpoint Indicates use of checkpointing in a copy step.
Restart
Restart Indicates whether the Process was restarted.
Source Disp 1 Source file disposition parameters.
Source Disp 2 Source file disposition parameters.
Source Disp 3 Source file disposition parameters.
Record Count Number of data records read or written.
Xmit Bytes Number of data bytes plus RU bytes sent
Xmit RUs Number of request/response units sent.
Dest File Name of the destination file.
Dest Disp 1 Destination file disposition parameters.
Through the output display, you can accomplish the following tasks:
v View details associated with a Process
v View the condition that caused a warning flag on a Process
v Change the order of fields displayed
Procedure
Notification
When you install Sterling Connect:Direct for Microsoft Windows, you identify the
method used to notify a user of Process execution. If you want to change the
method used to notify selected users when a Process executes, use the Change
Notification utility. This application updates the Registry entries used by Sterling
Connect:Direct to perform the specified notification.
Notification Methods
NT Broadcast
Sterling Connect:Direct for Microsoft Windows uses the msg command to
accomplish notification through NT Broadcast. The notification is sent to the
specified user or users attached to a particular computer or domain on behalf of
the user context that Sterling Connect:Direct is running in.
Procedure
1. Validate that the Sterling Connect:Direct service has been stopped by selecting
Start > Settings > Control Panel > Administrative Tools > Services and
making sure the Sterling Connect:Direct service is stopped. If not, select the
service and click Action > Stop.
2. Click Start > Programs > IBM Sterling Connect:Direct > v4.6.00 > CD Change
Notification Utility.
3. In the Node Name field, type or select the local node to configure. The current
notification for the node is displayed in the Transport field.
4. NT Broadcast is the default setting for the notification methods. If want to use
SMTP as the notification method, select SMTP in the Transport field and type
the following information in the fields provided:
v Host Address—SMTP server address, as the DNS name or IP address.
v Host Port—Port to connect to the SMTP server. Default=25.
v Sender—e-mail address uses for the sender.
v Turn on Authentication to enable it. Provide a user ID and password to sign
on to the SMTP server.
5. Click Save.
6. Click OK.
Sterling Connect:Direct for Microsoft Windows also uses the Microsoft Windows
Event Logging facility to log certain messages that the server generates during
execution. Sterling Connect:Direct selects specific record IDs or event types when
logging statistics. Sterling Connect:Direct assigns these record IDs severities and
passes them on to the Microsoft Windows Event Logging facility. The event.log
initialization parameter controls the statistics IDs that Sterling Connect:Direct sends
to the Microsoft Windows event log.
The statistics file stores information about all events that take place within the
Sterling Connect:Direct server for a specific period of time. The amount of time is
determined by the value specified for the stat.max.age initialization parameter.
Each record within the statistics file consists of fields that contain general
information about the record and a field that contains the statistics or audit
information to log.
In the fixed portion, the following fields are defined for the statistics files:
If the existing statistics file cannot be extended, the server issues a message to the
Microsoft Windows event log and terminates immediately. The server terminates
all activity as if issuing a stop command with the immediate parameter. Any
statistics records that are usually written during stop immediate processing are not
created in this situation.
Field Definition
Log Specifies the date and time the statistics record was created.
Date/Time
Type Specifies whether the record is event or Process related.
Each row is a statistics record. Select the row to view statistics record details. You
can also modify the appearance of the Statistics Monitor window.
The stat.max.age parameter controls the amount of time that the server retains the
statistics record in the database. When statistics records reach the value specified
by the stat.max.age parameter, the server automatically deletes them. To retain all
of your records, back up your database regularly or set stat.max.age= to disable
automatic deletion.
Procedure
1. To open a new statistics monitor, select File > New > Statistics Monitor.
2. To modify an existing statistics monitor, select File > Open and select from the
Statistics Monitor directory.
3. To view statistics for all Processes executed over a specific period of time:
a. Select All Statistics for Last _ hrs.min.
b. Enter the time period in hours and minutes.
c. Click OK.
4. To view only those Processes that meet certain criteria:
a. Select Filter Using Selection Criteria Pages.
b. Define the criteria on the remaining property pages.
5. To view statistics based on step and Process completion only select Step and
Process Completion Statistics Only.
6. To refresh the monitor at specified intervals:
a. Select Refresh every _ minutes.
b. Type the interval in minutes (1–60).
7. To view new statistics that were created since the Statistics Monitor was
closed, select Refresh on open.
8. To view the last statistic as it occurs, select Autoscroll.
9. If necessary, select the node to monitor in the Node field.
10. Click OK.
The Process number is the number assigned by Sterling Connect:Direct when the
Process is submitted.
Procedure
1. Open or create a Statistics Monitor.
2. Select Filter Using Selection Criteria Pages.
3. Click Add.
4. To view statistics based on Process name:
a. Click the Process tab.
b. Click the New icon.
c. Type the Process name and press Enter.
d. Continue the previous two steps until you have added all Process names
to monitor.
5. To view Statistics based on Process number:
a. Click the New icon.
b. Type the Process number and press Enter.
c. Repeat this step until you have added all Process numbers to monitor.
6. To view statistics based on a user ID:
a. Click the Nodes tab.
b. Click the New icon.
c. Type the user ID or user proxy and press Enter.
d. Repeat the previous two steps until you have added all user IDs to
monitor.
7. To view statistics based on who submitted a Process:
a. Click the Submitter tab.
b. Type the user ID or user proxy.
c. Type the node on which the user is located.
d. Click Add.
e. Repeat the previous three steps until you have added all submitters to
monitor.
8. To view statistics based on a range of date or time:
a. Click the Ranges tab.
b. Activate the Date/Time Range option.
c. Select one of the following options:
v Range—Type the time range to monitor in hours and minutes.
v Start and Stop—Type the beginning and ending date and time range or
select the date from the calendar in the Start and the Stop fields. Type
the date in the format mmm/dd/yyyy and the time in the format
hh:mm:ss Xm.
Option Description
Conditional To limit the statistics based on error code values, select the condition
Code Range code delimiters in the first drop-down box including:
Delimiters v Equal to
v Greater than or equal to
v Greater than
v Less than or equal to
v Less than
v Not equal to
Conditional To limit the statistics to selected error codes, select the error code value
Code Range from this drop-down box including:
Error Codes v 0
v 4
v 8
v 16
v Any
Field Description
Log Date/Time The date and time the statistics record was created.
Type The record category.
Record ID Category
CHGP Event
COAC Event
CRHT Event
CSTP Event
CTRC Process
CTRM Event
CUKN Event
CXIT Event
DELP Event
FLSP Process
FMRV Process
FMSD Process
GPRC Process
IFED Process
LIEX Event
LIOK Event
LWEX Event
NAUH Event
NMOP Event
NUIC Event
NUTC Event
NUIS Event
NUTS Event
PERR Process
PFLS Process
PRED Process
PSAV Event
After you close the reformatted display, that format becomes the default format.
The event log receives the following information from Sterling Connect:Direct for
Microsoft Windows:
The following sample uses the event.log initialization parameter to log Process
start and stop, Process flush, and Process errors to the event log.
event.log=PERR,PFLS,PRED,PSTR
If you want to view a category of events in the log, you can sort the event log by
using the Filter Events option. You can filter the event log by specifying settings
that control a range of events by date and time. You can also filter the event log by
particular event types, application source and category, particular user, computer,
Note: You can also view messages with the select message command from the CLI.
Viewing Messages
About this task
Use the Sterling Connect:Direct Message Lookup Utility to view the short and long
text explanations for error messages.
Procedure
1. Select Start > All Programs > IBM Sterling Connect:Direct > v4.6.0 > CD
Message Lookup.
2. Enter the message ID in the Message ID field.
3. Click Lookup to display the short and long message text.
To activate SNMP trapping, set the SNMP initialization parameter to Y. The default
is N.
The configuration file is used by both SNMP and event logging. It is specified by
the SNMP.DSN initialization parameter and the default file name is:
Chapter 3. System Guide 109
installation directory/snmp/snmp.ini
The configuration file enables you to customize the events that can be trapped. By
default, all events are enabled. If you want to disable some events or define other
messages to be trap events, edit this file with any standard editing tool.
When the server is started, the SNMP and EVENTLOG initialization parameters
are checked. If the SNMP and EVENTLOG parameters are not specified, SNMP
and event logging are not activated.
Alarm trap variables signal events that are critical to the operation of Sterling
Connect:Direct for Microsoft Windows. Status trap variables signal events that are
not critical to the operation of Sterling Connect:Direct for Microsoft Windows but
show valuable information. The tables in the following sections describe the
predefined traps, the message that triggers the trap, and a description of the trap
and associated text.
Valid values for all events are YES (or Y) to enable and NO (or N) to disable.
This section identifies the Sterling Connect:Direct traps supported and identifies
the messages associated with the trap. Sterling Connect:Direct traps are defined in
two groups: status traps and alarm traps.
v Status traps are not critical to the operations of Sterling Connect:Direct for
Microsoft Windows but display important information.
v Alarm traps are more serious.
Initialization Events
The following table details status events that occur at initialization.
Shutdown Events
The following table details status events that occur at shutdown.
The following table details the alarm event that occurs at shutdown:
API Events
The following table details the status event that occurs from the API.
The following table details alarm events that occur when a Process executes:
Miscellaneous Events
The following table details other status events.
For example, when you save a file, the Save activity record is stored, with the file
name of the saved document. The Activity Log is created at startup. It is
minimized and located in the lower left-hand corner. You may create, save, open,
close, and print Activity logs. When you open a new activity log, the active Log
that is already open is deactivated.
The activity log information is lost when you close Sterling Connect:Direct
Requester unless you set the activity log information to write to a file.
Procedure
1. Select Tools > Options.
2. To display the activity log in the output window, check Enable the activity log
in the output window.
3. To write the activity log to a file:
a. Select Write the Activity Output to a File.
b. Type the name of the file.
c. To create a new activity log every time you start Requester, select Create
New File at Startup.
d. To append activity to the existing log file at start up, select Append to
Existing Activity File.
4. Click OK.
Type Events
Use the events in the following table to enable or disable all alarm or status events.
The main window contains an icon representing the local computer and a traffic
light icon for each Sterling Connect:Direct node on the computer. A running server
is represented by a green light, a stopped server is represented by a red light, and
a server in the process of starting or stopping is represented by a yellow light.
Select To
Start a server. The traffic light icon displays a green light when the server is starting
or running.
Stop a server. The traffic light icon displays a red light indicating the server is not
running.
Set general properties for a Sterling Connect:Direct for Microsoft Windows server.
Stop the server before setting general properties.
Display the About Admin Tool dialog box.
Click a menu bar or toolbar item, to access a description of its function. This action
does not work when a dialog box is open.
Use the Admin Tool utility to start and stop a Sterling Connect:Direct server.
Procedure
1. Select the server to start or stop.
2. Select Server > Start. If the server is already started, the server icon changes to
yellow and then changes to green. If the server is unable to start, the light
changes back to red.
To configure general, TCP/IP, SNA, and database properties for a server, use the
Properties dialog box.
CAUTION: You must stop the Sterling Connect:Direct service before you configure
properties. Stopping the service interrupts any Processes that are running.
Procedure
1. Click the server to configure.
2. If the server is running, click the stop icon to stop the server.
3. Select Server > Initialization Properties.
4. Select one of the following Service Startup methods from the pull-down
menu:
v Automatic to start Sterling Connect:Direct every time the system starts.
v Manual to start Sterling Connect:Direct manually.
v Disabled to prevent Sterling Connect:Direct from being started.
5. If necessary, change the settings on the General properties page. Refer to the
following table for a description of the fields:
6. Click the API tab. If necessary change the default values of API fields. Refer to
the following table for a description of the fields:
8. Click the UDT tab. If necessary change the default values of UDT fields. Refer
to the following table for a description of the fields:
9. Click the SNA tab. If necessary, change SNA field values. Refer to the
following table for a description of the SNA fields:
You can also view or print a report that lists all nodes that are registered in Active
Directory. In order to add or delete a node from Active Directory, you must be a
member of the Enterprise Admins group.
Note: You can only add or delete Active Directory entries if Active Directory
services have been implemented in your environment.
Procedure
1. Start the Admin Tool utility.
2. Select Active Directory > Create.
3. Select the node to add and click Add.
Procedure
1. Start the Admin Tool utility.
2. Select Active Directory > Delete.
3. Select the node to delete and click Remove.
Procedure
1. Start the Admin Tool utility.
2. Select Active Directory > Report. The Active Directory Report is displayed.
Refer to “Traceoff Command” on page 173 and Traceon Command for instructions
on using the CLI to define or turn off traces.
Defining a Trace
About this task
Procedure
1. Start Requester.
2. Select Admin > Tracing.
3. To set trace information for selected functions, turn on tracing for the specific
Sterling Connect:Direct events.
v CMGR—Capture the interaction between clients and the server.
v PMGR—Capture server Process changes.
v MAIN—Capture server initialization and termination.
v STAT—Capture statistics activity.
v SMGR—Capture the execution of Processes and the interaction of the server
with other nodes.
v COMM—Capture interactions with external communications facilities
invoked from Session Manager.
4. To set tracing for all available events, click Full Tracing.
5. Generate a configuration report is selected by default. If you do not want to
generate a configuration report, turn off this option.
6. To specify output file information:
a. Click the File tab.
Stopping a Trace
About this task
To stop a trace:
Procedure
1. Select Admin > Tracing.
2. Set the trace that you want to stop to OFF.
3. Click All Off to turn off all tracing.
4. Click OK.
p — Starts a Process Manager trace. This trace shows all events related
to the Process Manager and to Session Manager startup by the main
server executable.
b — Starts a basic trace that includes only module entry and exit
records. This is the default.
f — Starts a full trace that shows all trace data produced by i plus
certain Sterling Connect:Direct control blocks and internal information.
-twrp Specifies that the trace file should wrap once it reaches its maximum
size.
-tfil=filespec Specifies the fully qualified name of the trace file that receives output.
The default is CDTRACE.CDT in the directory where the Sterling
Connect:Direct for Microsoft Windows server executable resides.
Microsoft Windows Services treats a backslash (\) as an escape character,
so type two backslashes for each backslash in the file path.
Example:
-tfil=c:\\users\\default\\trace.it
bytesK: You can specify the file size by using the K (x1000) suffix.
bytesM: You can specify the file size by using the M (x1000000) suffix.
For Session Manager (s) or Communications (o) trace types, the following
parameters are also available:
Sterling Connect:Direct uses the following facilities to address errors for Process
recovery:
v Process step restart
v Automatic session retry
v Checkpoint/restart
v Run Task restart
When you release the Process for execution, Sterling Connect:Direct automatically
begins execution at the beginning of that statement. No user specification is
required for Process step restart. Sterling Connect:Direct always performs Process
step restart.
If a session error occurs, the Process moves to the Timer queue in retry (RE) status
and short-term and long-term wait times begin. After short-term and long-term
wait times expire, the Process is moved to the Hold queue.
The file sender provides positioning information to the receiver when a checkpoint
interval is reached. The receiver stores this information, along with its destination
file positioning information, in the checkpoint file. The last four sets of positioning
information are retained in the checkpoint file. At restart, each set of information is
used until the file is successfully repositioned. If repositioning fails, then the entire
file is retransmitted.
Note: See the IBM Sterling Connect:Direct Process Language Reference Guide for use of
the checkpoint parameter in the copy statement.
If a run task Process step restarts, the node where the operation executes attempts
to find the checkpoint information in the TCQ header. If the run task step is still
executing, the Process that is running for the restart of the step waits for the run
task operation to finish the first task and proceed to the next step of the Process, if
there is one.
When the first Process finishes, it determines that the session under which it was
running has been lost and terminates without logging statistics records that
indicate a session failure. The second Process records how the run task step that
was still executing ended and proceeds to the next step in the Process.
If Sterling Connect:Direct determines at restart that the run task operation ended
because it finished before the PNODE restarted the Process, then the run task step
does not execute again. However, if the run task operation did not finish and is not
currently running, then the value of the runtask.restart initialization parameter
determines whether to restart the Process.
Note: For a full description of all run task statement parameters, see the IBM
Sterling Connect:Direct Process Language Reference Guide.
If you are troubleshooting a Sterling Connect:Direct for z/OS server, gather the
following information:
v Network map parameter definitions
v Local Node source
v Remote Node source
v For SNA connectivity, provide the following:
– z/OS LU definition
– z/OS PU definition
– z/OS APPLID
– z/OS LOGMODE definition entry
Worksheets
Buffer Size
CRC
UDT Communications Mode Name
Buffer Size
CRC
APPC Communications Mode Name
Max RU Size
Max Sessions
Note: See “Define and Manage the Sterling Connect:Direct Network” on page 55
for field content.
Make a copy of this worksheet for each communications path in the network.
Communications
Path Information Needed
TCP/IP Communication Path Name
Communications Mode
UDT Communication Path Name
Communications Mode
Communications Mode
Transport Type
SDLC
v Local SNA Network
v LU Name
Use the information on this worksheet when you modify your network map. See
“Define and Manage the Sterling Connect:Direct Network” on page 55 for field
content.
Note: The components below correspond to the tabs on the Netmap Node
Properties dialog box.
Network Map
Component Information Needed
Main Options Node Name
Operating System
Default Class
Partner LU Name
APPC Mode
Communications Communications Path Names
Path
Note: You must designate at least one path.
Description Contact Name
Information
Contact Phone Number
Comment
See “Configuring the Sterling Connect:Direct Local Node” on page 45 for field
content. Make a copy of this worksheet for each Sterling Connect:Direct user.
Type of Authorization
Information Information Needed
Main Options Local User ID
Note: See “Configuring the Sterling Connect:Direct Local Node” on page 45.
Type of Authorization
Information Information Needed
Main Options Remote Node Name
Remote User ID
Local User ID
Upload Directory
Download Directory
Process Directory
Program Directory
Category Description
Miscellaneous Miscellaneous commands describe server path, download and
upload directories, dialup entries, and security exits.
Statistics Information Statistics settings determine the maximum age that statistics
records are kept and what commands are logged in the
statistics file.
[Miscellaneous Commands]
server.path=C:\Program Files\Sterling\Connect Direct v4.6.00\Server\
proc.prio.default=10
exec.prio.default=7
download.dir=C:\Program Files\Sterling\Connect Direct v4.6.00\Server\DOWNLOAD\
upload.dir=C:\Program Files\Sterling\Connect Direct v4.6.00\Server\UPLOAD\
program.dir=C:\Program Files\Sterling\Connect Direct v4.6.00\Server\PROGRAM\
restrict.cmd=N
security.exit=<None>
notify.level=A
file.exit=<None>
event.log=All
snmp=N
snmp.eventlog=N
snmp.trapstat=Nsnmp.dsn=C:\Program Files\Sterling\Connect Direct v4.6.00\Server\
snmp\snmp.ini
certificate.directory=C:\Program Files\Sterling Commerce\Connect Direct v4.6.00\
Server\Secure+\Certificates
s+cmd.enforce.secure.connection=Y
The example below shows the parameters related to the Transmission Control
Queue (TCQ):
[TCQ Information]
tcq.max.age=30
tcq.start=W
process.dir=C:\PROGRAM FILES\STERLING COMMERCE\CONNECT DIRECT V4.6.00\SERVER\
PROCESS\
runtask.restart=N
Procedure
1. Click Start > All Programs > IBM Sterling Connect:Direct > v4.7.00 > CD
Requester.
2. In Sterling Connect:Direct Requester, select Admin > Initialization Parameters.
If you have not attached to Sterling Connect:Direct, the Connect:Direct Attach
dialog box is displayed.
3. Attach to the server.
4. In the initialization parameters file, place the cursor after the equal sign
following the parameter you want to change.
5. Type the new value. Refer to the parameters tables for the name, definition,
and valid values for each command parameter.
6. Select Initparms > Apply to update and save changes.
7. Close the Initparms dialog box by clicking the X in the upper-right-hand
corner.
Miscellaneous Parameters
The miscellaneous parameters determine the server path, default Process priority,
event log values, and various restricted directories.
c (cold)—Delete all
existing Processes in the
TCQ at startup.
process.dir The default directory a Process Valid, fully qualified path
runs from if a submit statement name.
does not specify a fully-qualified
path. The default is
X:\installation
directory\PROCESS.
runtask.restart Specifies whether a run task Y|N
operation executes on a remote
Windows node after a session The default is N.
failure. If a run task operation is
executing on the remote node and
a session failure occurs, the local
node recognizes the session failure
and puts the Process in the Timer
queue for retry. The remote node
is not aware of the session failure
until the Process completes. The
checkpoint/restart feature for run
task ensures that when the Process
restarts on the local node, the run
task operation does not execute
again on the remote node.
conn.retry.exhaust.action Action to take after the specified Hold | Delete
short and long-term retries have v Hold - Places Processes
been used. in the hold queue in
"Held in Error” status
after all retry attempts
are used.
v Delete - Causes the
Processes to be deleted
from the TCQ.
Statistics Parameters
The Sterling Connect:Direct statistics facility logs information about Sterling
Connect:Direct operations. The statistics information parameters define the
characteristics of the statistics facility, such as the maximum age of a statistics
record.
Specify an IP Address
You can enter IP addresses/host names and ports in several ways depending on
the field you are specifying:
v Address or host name only
v Port number only
v Address/host name with a port number
v Multiple address/host name and port combinations
IP Addresses
Sterling Connect:Direct for Microsoft Windows accepts both IPv4 and IPv6
addresses. Wherever an IP address is specified in Sterling Connect:Direct for
Microsoft Windows, you can use either IPv4 or an IPv6 addresses.
IPv4 Addresses
IPv6
2001:0db8:85a3:0000:1319:8a2e:0370:1337
can be shortened as
2001:0db8:85a3::1319:8a2e:0370:1337
001:0db8:0000:0000:0000:0000:1319:58ab
2001:0db8:0000:0000::1319:58ab
v Leading zeros in a four-zero group can be left out (0000 can be shortened to 0).
For example:
2001:0db8:0000:0000::1319:58ab
2001:0db8:0:0:0:0:1319:58ab
v You can write a sequence of 4 bytes that occur at the end of an IPv6 address in
decimal format using dots as separators. For example:
::ffff:102:304
or
0000:0000:0000:0000:0000:ffff:0102:0304
::ffff:1.2.3.4
Host Names
When you specify a host name rather than an IP address, Sterling Connect:Direct
for Microsoft Windows does a DNS lookup to get the IP address from the
operating system. The first IP address returned in the DNS lookup is used
regardless of whether it is in IPv4 or IPv6 format.
A port number must be in the range of 0 through 65535. Port numbers lower than
1024 are designated as reserved and should not be used. The following examples
show port numbers appended to IP/host addresses using these conventions:
10.23.107.5;1364
fe00:0:0:2014::7;1364
msdallas-dt;1364
A space can be added after the comma for readability. For example:
You can also specify a port number for each address or host name. The port is
separated from its corresponding address/host name with a semicolon (;), and
each address/host name and port combination is separated by a comma (,). A
space may be added after the comma for readability. The following example shows
multiple address/host name and port combinations:
Multiple address/host names (and combinations with port numbers) are limited to
1024 characters.
Sterling Connect:Direct for Microsoft Windows supports masks for both IPv4 and
IPv6 addresses, as shown in the following sample entry from the initparms.cfg file:
(199.2.4.*, 1000)—Any IPv4 address that falls in the range from 199.2.4.0 through
199.2.4.255 and uses only port 1000.
(fd00:0:0:2015::0/48, 6000, 7000)—Any IPv6 address that falls in the range from
fd00:0:0:2015:0:0:0:0 through fd00:0:0:ffff:ffff:ffff:ffff:ffff and uses port 6000 or port
7000.
As shown in the sample entry above, the wildcard character (*) is supported to
define an IP address pattern. You can specify up to 255 unique IP address patterns
or up to 1024 characters in length, each with its own list of valid source ports. If
the wildcard character is used, the optional mask is not valid.
If you prefer to use a command line interface, use the CLI to issue requests
interactively, or you can submit them automatically from batch files or command
files. The CLI enables you to perform the following tasks:
v Connect to the Sterling Connect:Direct server
v Issue Sterling Connect:Direct commands
v Submit a Process
v Change a Process
v Delete a Process
v Retrieve Process status information
v Retrieve Process statistics records
If you want to connect to a Sterling Connect:Direct server using the CLI, use the
Logon Connection utility.
This utility can be used to run batch-oriented jobs. It enables you to identify the
parameters necessary to connect to a server. It then saves this information to a
configuration file. If you do not identify a directory, the file is saved in the root
directory.
Procedure
1. Type the following command to run the LCU batch file:
LCU -fx:\directory\filename
where x:\directory is the location to save the configuration file and file name is
the name of the configuration file.
2. Enter the following information to identify the connection parameters for the
server:
v IP Address of the Sterling Connect:Direct server
v Port number of the Sterling Connect:Direct server
v User ID to use to connect to the server
v User password of the user ID used to connect to the server.
The information is automatically saved to the file you identified with the
x:\directory\filename variable. If you do not enter this variable, the
configuration file is saved in the root directory to the file called cddef.bin.
Procedure
1. From a command prompt, navigate to the Common Utilities directory where
the CLI is installed or define the CLI location in the user's path.
2. To start the CLI, type the following command, including any of the parameters
you wish to specify:
Parameters Description
-fLogonFile File to use to automatically connect to a Sterling
Connect:Direct server.
-nNodeName Node name or IP address.
-uUserId User ID to use to connect to the node.
-pPassword Password to use connect to the Sterling Connect:Direct node.
-l By default, the CLI limits output to 128 characters per line.
Include this switch to display longer lines, such as file names
or sysopts strings.
quit;
CLI Commands
The following table provides a summary of all available commands that can be
used with the CLI.
pname=(payproc,arproc,ivproc,a?prod5*)
Piping Conventions
The Sterling Connect:Direct for Microsoft Windows CLI supports the following
piping conventions:
v <filename.ext uses the file for input
v >filename.ext uses the file for output
submit
test process snode=dsd.unix
cp copy from (file=testfile.dat pnode)
to (file=test.dat snode)
pend;
select statistics;
select process;
quit;
By typing the following command, you can execute all of the commands in the
COMMANDS.TXT file.
Parameters override the same parameters specified in the Process statement. The
submit command also enables you to resolve symbolic parameters found in the
Process.
Parameter Description
file=filename The name of the Process file, up to 256 characters. If you specify the file
parameter, you must specify it before any other parameter. If you do not
specify this parameter, then the text of the Process must follow the submit
command.
class=nn| session number The node-to-node session on which a Process can execute. A Process can
execute in the class specified or any higher session class.
execprty=nn The operating system execution priority, from 1 to 15, of the Process. The
execution priority parameter is used to influence the priority given to the
Session Manager when it starts this Process. The higher the priority, the
higher the Session Manager priority and, therefore, the more system
resources. Scheduling Processes to run in the High priority class can have an
adverse effect on the execution of other applications in the system.
The values for the execution priority range from 1 to 15 and are mapped to
Microsoft Windows Process priority classes and values. The highest priority
is 15.
yes—Places the Process in the Hold queue in HI (Held Initial) status until
you explicitly release it by a change process command. When you specify
both hold=yes and a startt value, the hold specification takes precedence. A
Process with hold=yes is placed in the Hold queue even if you specify a
start time.
no—Does not place the Process in the Hold queue. The Process executes as
soon as resources are available.
call—Holds the Process until the SNODE connects to the PNODE. At that
time, the software releases the Process for execution. It also releases the
Process when another Process on the PNODE connects to the SNODE.
pacct=“pnode accounting data” A string, up to 256 characters, to be used as accounting data for the
PNODE. Enclose the string in double quotation marks.
pnodeid=(id , pswd) Security user IDs and passwords at the PNODE. The subparameters can
contain 1 to 48 alphanumeric characters. You must specify both the ID and
the password.
If the time interval expires, the command processor returns a warning status
code and message ID. The Process is not affected by the time interval
expiration and executes normally.
yes—Specifies that the software retains the Process in the Hold queue in HR
status after execution. Issue a change process command to release the
Process for execution.
initial—Specifies that the software is to retain the Process in the Hold queue
in HR status for automatic execution every time Sterling Connect:Direct
initializes.
If startt is set, you must set retain=yes to execute the Process at regular
intervals based on the value of startt.
If retain=initial, do not use the startt parameter. This causes the submit
command to fail.
Specify the host name or IP address, a semicolon, and the port number or
service name. For more information on specifying valid IPv4 and IPv6
addresses and ports, see Specifying IP Addresses, Host Names, and Ports.
If you specify the password, you must also specify the ID. If you specify a
new password, you must also specify the existing password.
prty=nn The selection priority of the Process for execution. This priority parameter is
used for Process selection. A Process with a higher priority is selected for
execution before a Process with a lower priority. The priority value does not
affect the priority during transmission.
date—Specifies the day, month, and year, that you can code as
mm/dd/yyyy or mm-dd-yyyy. You can code month and day as one or two
digits and year as two or four digits. 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, tomorrow, Monday,
Tuesday, Wednesday, Thursday, Friday, Saturday, and Sunday.
If the time you specify has already passed, Sterling Connect:Direct schedules
the Process for the next valid date and time. For example, if you set the
Process to start daily at 5:00 PM, or startt=(, 17:00), and the Process submits
at 5:30 PM, Sterling Connect:Direct schedules the Process to run the next
day.
If you specify only the day value, the time defaults to midnight (00:00:00).
This means that if you submit a Process on Monday, with Monday as the
only startt parameter, the Process does not run until the following Monday
at midnight.
Do not set the startt parameter if retain=initial. This causes the submit
command to fail.
&symbolic name n=“variable string A symbolic parameter assigned a value. The value is substituted within the
n” Process when the software encounters the symbolic parameter. The symbolic
within the Process must be enclosed within quotes.
Examples
The following command submits the Process named payroll.cdp. Because the
command specifies retain=yes, the Process is retained in the TCQ after execution.
The Process starts the next Monday at 00:00:00. The command specifies Process
accounting data for the PNODE.
The following command submits the Process named copyfil.cdp. Because the
command specifies startt, the Process executes on the first day of January 2003 at
11:45 a.m.
Select the Processes to change by Process name, Process number, SNODE name,
submitter ID, or a combination of these.
Note: All changes affect the Process in the TCQ, not the original text of the Process
as submitted.
Command Parameters
change process /* Search Criteria */
[pname=Process name | generic | (list)]
[pnumber=Process number | (list)]
[snode=snode name | generic | (list)]
[submitter=(node name, userid) | generic | (list)]
/* The following parameters specify the characteristics of Sterling
Connect:Direct Processes that you can modify. */
class= | session number
execprty=nn
hold=yes | no | call
newsnode=new snode name
release
prty=nn
Search Parameters
Parameter Description
pname=Process name | generic | The name of the Process or Processes. The name can
(list) be 1 to 8 alphanumeric characters long.
pnumber=Process number | (list) The Process number of the Process. The Process
numbers are assigned when you submit the Process.
Valid Process numbers range from 1 to 999999.
snode=snode name | generic | Searches for a Process or Processes by the SNODE
(list) (partner) name. The SNODE name can contain 1 to 16
alphanumeric characters. You can use the IP address
of the SNODE as your SNODE name.
submitter=(node name, userid) | Searches for a Process or Processes by the node
generic | (list) specification and userid of the Process owner. The
maximum combined length, including the node name
and userid for this parameter, is 66 characters.
Parameter Description
class=nn | session number Changes the node-to-node session on which the
Process can execute. A Process can execute on the
specified class or any higher session class.
execprty=nn The execution priority of the Process. The values for
the execution priority range from 1 to 15 and are
mapped to Microsoft Windows Process priority
classes and values. The highest priority is 15.
Example
The following command changes the SNODE name for any nonexecuting Process
named cdproc to a new SNODE name, paris.
Command Parameters
delete process /* Search Criteria */
[pname=Process name | generic | (list)]
[pnumber=Process number | (list)]
[snode=snode name | generic | (list)]
[submitter=(node name, userid) | generic | (list)]
/* Processing Parameters */
[force=yes | no]
[hold=yes | no]
Search Parameters
Use the parameters to identify the Processes you want to delete. You can delete
Processes by name, number, node, or a combination of the criteria.
Parameter Description
pname=Process name | generic | The name of the Processes, from 1–8 alphanumeric
(list) characters, to delete.
pnumber=Process number | (list) The number of the Process to delete. The Process
number is assigned when the Process is submitted.
snode=snode name | generic | The SNODE name of the Processes to delete. The
(list) SNODE name can be 1 to 16 alphanumeric characters
long.
submitter=(node name, userid) | The submitter node name and user ID of the
generic | (list) Processes to delete. The maximum combined length,
including the node name and user ID, is 66
characters.
Processing Parameters
Define one or more of the following parameters to identify how the deleted
Processes are managed:
Parameter Description
force=yes | no Forcibly terminate an executing Process. Use this
parameter if a Process is in the executing state and is
waiting for unavailable resources.
Examples
The following command deletes all Processes submitted by userid cduser on node
dallas. If the Processes are executing, it stops and removes them from the TCQ.
The following command deletes all Processes named rome from the TCQ. If the
Processes are executing, the command forcibly terminates them.
Format
Command Parameters
select process /* Selection Criteria */
[pname=Process name | generic | (list)]
[pnumber=Process number | (list)]
[queue=all | exec | hold | wait | timer]
[snode=snode name | generic | (list)]
[status=ex | hc | he | hi | ho | hr | hs | pe | re | wa | wc | ws
| (list)]
[submitter=(node name, userid) | generic | (list)]
/* Display option */
[detail=yes | no]
Selection Parameters
Specify one or more of the following selection parameters. If you do not specify
one of the following selection parameters, all Processes in the TCQ you are
authorized to access are selected.
The following display parameter generates a detailed report of the select process
command.
Parameter Description
detail=yes | no Specifies the type of report generated for the selected Process or
Processes. The default is no.
Examples
The following example shows the report information returned when specifying
detail=yes.
==================================================================
SELECT PROCESS
==================================================================
Process Name =>SAMPLE Class =>
Process Number =>38 Priority =>
Submitter Node =>CSDPUBS Pnode CSGPUBS
Submitter user1 Snode CSGPUBS
Retain Process =>N
Submit Time =>09:54:33 Schedule Time =>
Submit Date =>10/30/2002 Schedule Date =>
Queue =>HOLD
Process Status =>HI
Message Text =>
--------------------------------------------------
Process Name =>SAMPLE Class =>
Process Number =>39 Priority =>0
Submitter Node =>CSGPUBS Pnode =>CSGPUBS
Submitter user Snode =>CSGPUBS
Retain Process =>N
Submit Date =>09:54:35 Schedule Time =>
Submit Date =>10/30/2002 Schedule Date =>
Queue =>HOLD
Process Status =>HI
Message Text =>
--------------------------------------------------
The following example shows the report information returned when specifying
detail=no or omitting the detail parameter.
Format
Command Parameters
select message Selection Criteria
msgid=message ID
Parameter Description
msgid=message id The Sterling Connect:Direct message ID of
the message request. Do not use generic
specifications. This parameter is required.
Example
Type the following command at the CLI prompt to retrieve the text of Sterling
Connect:Direct message LCCC00I:
select message msgid=LCCC00I;
When using the select statistics command, specify your selection criteria carefully
to avoid displaying excessive volumes of records. If you do not provide selection
criteria, all records for the day are retrieved.
Command Parameters
select statistics /* Selection Criteria */
[ccode=(operator, code)]
[dfile=destination filename | (list)]
[pname=Process name | generic | (list)]
[pnumber=Process number | (list)]
[reccat=caev | capr | (caev,capr)]
[recids=record id | (list)]
[snode=snode name | generic | (list)]
[sfile=source filename | (list)]
[startt=([date | day][, hh:mm:ss[am|pm]])]
[stopt=([date | day][, hh:mm:ss[am|pm]])]
[submitter=(node name, userid) | generic | (list)]
Note: To use a wildcard within the submitter parameter, you must
have administrator access.
/* Display option */
[detail=yes | no]
Parameters
Provide one or more of the following parameters to determine what statistics are
returned:
ne | != Not equal
COAC—Communication activated
LIOK—Listen okay
PPER—Pipe error
PRED—Process ended
PRIN—Process interrupted
SBED—Submit complete
SERR—System error
SNMP—SNMP
TCPI—TCP started
Provide this optional parameter if you want to generate a report of the statistics
that are generated:
Parameter Description
detail=yes | no Specifies the type of report generated for the selected Processes.
The default is no.
Example
The following example shows the report information returned when specifying
detail=yes.
==================================================================
SELECT STATISTICS
==================================================================
PROCESS RECORD Record Id=>SUBP
Process Name =>SAMPLE Stat Log Time =>09:54:33
Process Number =>38 Stat Log Time =>07/30/2003
Submitter Id =>user1
Snode =>CSGPUBS
Completion Code =>0
Message Id =>
Short Text =>
---------------------------------------------------------
PROCESS RECORD Record Id=>SUBp
Process Name =>SAMPLE Stat Log Time =>09:54:33
Process Number =>39 Stat Log Time =>07/30/2003
Submitter Id =>user1
Snode =>CSGPUBS
Completion Code =>0
Message Id =>
Short Text =>
---------------------------------------------------------
The following example shows the report information returned when specifying
detail=no or omitting the detail parameter.
The following command generates statistics output for Process number 7. The
output consists of all records for that Process starting with those generated on July
11, 2003.
Traceoff Command
The Sterling Connect:Direct server provides a comprehensive trace facility that
assists in the diagnosis of problems relating to any facet of the operation of the
server. Use the traceoff command to disable a trace started with the traceon
command.
Format
Command Parameter
traceoff [file=filename]
[type=cmgr | pmgr | smgr | comm | (list)]
[dest=destination | (list)]
[pnode | snode]
[pname=process name | (list)]
[pnum=process number | (list)]
Note: The dest, pnode, pname, and pnum parameters are valid for smgr and
comm traces only.
Specify one or more of the following parameters to identify the trace to turn off
including the output file of the trace, the type of trace, the destination, the node,
and the Process name or number.
Parameter Description
file=filename The name of the trace output file. The
default is CDTRACE.CDT.
The following parameters are valid for SMGR and COMM trace types only. The
dest, pnode, snode, pname, and pnum parameters are mutually exclusive.
Parameter Description
dest=destination | (list) The destination node name of the Process you want to stop
tracing or a list of up to four node names.
pnode | snode The PNODE or SNODE session managers.
Example
The following command turns off the full SMGR trace for the Process named
payroll.
Traceon Command
Use the traceon command to enable the trace facility. The trace facility enables you
to capture information to assist in the diagnosis of Sterling Connect:Direct
problems.
Command Parameters
traceon [file=filename]
[filesize=nnK | nnM | 0]
[level=basic | intermediate | full]
[type=cmgr | pmgr | smgr | comm | (list)]
[wrap=yes | no]
[dest=destination | (list)]
[pnode | snode]
[pname=process name | (list)]
[pnum=process number | (list)]
Note: The dest, pnode, pname, and pnum parameters are valid for smgr and
comm traces only.
Parameters
Parameter Description
file=filename The name of the output file if you want to
write the trace information to a file. The size
of the name can range from 1 to 256
characters. The default is CDTRACE.CDT in
the Sterling Connect:Direct directory.
filesize=nnnK | nnnM | 0 The maximum file size as a number of
kilobytes (K) or megabytes (M). A value of 0
indicates that the file can grow indefinitely.
level=basic | intermediate | full The level of trace detail.
Help Command
Use the help command to receive a list of the commands supported by the Sterling
Connect:Direct CLI.
Any command with a –? or /? will display the syntax for the command's usage.
Format
Command Parameters
stop [force | immediate | step| quiesce]
Parameters
Parameter Description
force Forcibly terminates the Sterling
Connect:Direct server with no attempt to
terminate executing Processes in an orderly
fashion or write statistics to disk. Sterling
Connect:Direct releases all server resources,
including connections, LU 6.2 sessions,
memory, and semaphores. It retains all
active Processes in the TCQ and restarts
them when you restart the Sterling
Connect:Direct server.
immediate Begins an immediate, but orderly, shutdown
of all activity and terminates Sterling
Connect:Direct. The software terminates
connections, writes statistics records, closes
files, and shuts down. It retains all active
Processes in the TCQ and restarts them
when you restart the Sterling Connect:Direct
server.
step Shuts down Sterling Connect:Direct after all
currently executing Process steps complete.
The software writes statistics records, closes
files, and shuts down. To restart Processes at
the next step the next time you start Sterling
Connect:Direct, set the tcq.start initialization
parameter to require a warm start.
quiesce Runs all executing Processes to completion.
Sterling Connect:Direct starts no new
Processes.
stop force;
Translation Tables
Sterling Connect:Direct translates data from one character set to a different
character set, such as from ASCII to EBCDIC, using character translation tables.
These translation tables provide greater flexibility in the translation of data when
copying data to or from a Sterling Connect:Direct node.
Default translation tables are defined in the initialization parameters for the
Sterling Connect:Direct node. You also have the ability to specify a different
translation table in the sysopts parameter with each Copy statement. Sterling
Connect:Direct provides two standard translation tables for use when sending or
receiving data to or from a remote Sterling Connect:Direct node:
v XLATERCV translates data from EBCDIC to ASCII.
v XLATESND translates data from ASCII to EBCDIC.
Translation is only performed when the data type is text. No translation is done if
the data type is binary.
Procedure
1. Select Admin > Translation Table.
2. Type the name of the translation table file, or select one of the following default
translation tables from the drop-down list:
v XLATERCR.CDX
v XLATESND.CDX
3. Click OK.
Each cell stores the character value for the target character set. The source
character set is used as an index into the table. For example, an ASCII blank
(Hex 0) would fetch the byte at offset Hex 0 in the translation table. If the byte
at location Hex 0 contains Hex code 40, that would translate to an EBCDIC
code indicating a blank character.
4. To view the shortcut menu, right-click in the Translation Table dialog box.
5. Select one of the following representations for the table element:
v Hex
v Dec
To use Sterling Connect:Direct Requester, refer to “Define and Manage the Sterling
Connect:Direct Network” on page 55 for instructions.
The Sterling Connect:Direct for Microsoft Windows client software uses the
Microsoft Windows Registry to store its configuration information. The Client
Connection Utility allows you to update the connection settings within the
Registry.
CAUTION: Use the Client Connection Utility to update any Registry settings
rather than editing them directly.
You can view, edit, and update Sterling Connect:Direct for Microsoft
Windowsconnection settings in the Microsoft Windows Registry with the Client
Connection Utility. These settings enable communication between the user
interfaces and the Sterling Connect:Direct server. You can set up and update
connection settings in the following ways:
v Add and delete a node
v Add and delete a user
v Configure node and user properties
v Define 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.
Procedure
1. Click Start > All Programs.
2. Click IBM Sterling Connect Direct > v4.7.00 > CD Client Connection Utility.
The Client Connection Utility main window is displayed.
The Client Connection Utility lets you add new Sterling Connect:Direct nodes and
identify the properties of the nodes, 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).
Procedure
1. Select File > New Node.
2. To add a node registered in the Active Directory, follow these steps:
a. Select Windows in the Operating System field.
b. Select the node to add from Active Directory Nodes.
Note: Click Refresh to update the address and port stored on the local
computer with the values from the Active Directory listing.
3. To add a node that is not registered in the Active Directory, follow these steps:
a. In the Name field, type the name of the Sterling Connect:Direct node you
want to add.
b. If necessary, change the operating system value in the Operating System
field.
c. In the Address field, 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.
Attention: Changes made to the node settings are not written to the Registry
until you select Save.
Deleting a Node
About this task
To delete a node:
Procedure
1. In the Client Connection Utility main window, select the node you want to
delete.
2. Select Edit > Delete.
3. Select File > Save to delete the node.
Attention: Changes made to the node settings are not written to the Registry
until you select Save.
To add a new Sterling Connect:Direct user from the Client Connection Utility:
Note: Changes made to the node settings are not written to the Registry until
you select Save.
To delete a user from the node using the Client Connection Utility:
Procedure
1. Click the plus (+) sign next to the node containing the user you want to delete.
2. Select the user you want to delete.
3. From the Edit menu, select Delete.
4. From the File menu, select Save to delete the user.
Note: Changes made to the node settings are not written to the Registry until
you select Save.
Procedure
1. Do one of the following:
v To update a node, highlight the node you want to configure.
v To update a user, highlight the user you want to configure.
2. Select File > Properties.
The Client Connection Utility allows you to define a default node or default user.
The default node and user will be used by the Sterling Connect:Direct Requester
and the CLI.
Procedure
1. Do one of the following:
v To define a default node, highlight the node you want to designate as the
default.
v To define a default user, highlight the user you want to designate as the
default.
2. Select File > Save to save the settings.
Attention: Changes made to the node and user settings are not written to the
Registry until you select Save.
The Sterling Connect:Direct Client Connection Utility allows you to import and
export connection settings to a file. These settings can be saved and used on
another computer or node.
Procedure
1. Select the node to which to import the Registry settings.
2. Select File > Import.
CAUTION:
Importing a Registry settings file causes all current changes to the selected
node to be lost if they have not been saved.
3. Select the Registry settings file you want to import (.REX extension) and click
OK.
4. Select File > Save to save the settings.
Attention: Changes made to the node settings are not written to the Registry
until you select Save.
Procedure
1. Select File > Print.
2. Configure the print settings and click OK. A report of all Registry settings is
generated.
3. Select File > Print Preview to preview the Registry settings report.
4. Click Zoom In to enlarge the text and read the report.
5. Click Print to print the report, or click Close to close without printing the
report.
Note: Additional node detail is provided if the node has been used at least
once by the client software.
You can enable test mode for production instances of Sterling Connect:Direct for
Microsoft Windows to perform the following functions:
v Test new applications and customer connections
v Prevent future production work from executing until testing is complete after
you have terminated all active production work using the Flush Process
command
v Resume regular production work after testing
v Control individual file transfers by application
v Enable and disable individual nodes and applications
You can specify the following criteria that are used to find matches for one or more
Processes to include (using the “I” command code) or exclude (“X” command
code) from execution:
v A partial or full Process name
v A partial or full remote node name
v A partial or full Sterling Connect:Direct submitter ID and submitter node
combination
In addition to telling Sterling Connect:Direct which Processes to run, you tell the
system what to do with the Processes which do not get executed. You can specify
the following dispositions for Processes not permitted to run:
v Place the Process in the Hold queue
v Place the Process in the Timer queue for session retry
v Flush the Process from the queue
For more information on how the testing mode can be used, see “Sample Test
Scenarios” on page 186 in this section.
When the testing mode is enabled, Sterling Connect:Direct for Microsoft Windows
performs a syntax check on the parameter table and fails initialization if the table
is invalid. If the table is valid, Sterling Connect:Direct for Microsoft Windows scans
it looking for a pattern that matches the Process that is about to execute. If a match
is found, the Process is permitted to execute if the “I” (Include) command code is
in effect. If command code “X” (Exclude) is in effect, the process is not permitted
to execute. If a match is not found in the table, the opposite processing occurs from
the case where a match is found, that is, if no match is found and command code
“I” is in effect, the Process is not permitted to execute, whereas if command code
“X” is in effect, the Process is permitted to execute.
Note: For Processes initiated on remote nodes, the testing mode functions in the
same manner as it does for Processes submitted on the local Sterling
Connect:Direct node except that the remote node is the PNODE (Process owner)
for that Process, and the local node is the SNODE (secondary node). The
NDMPXTBL Parameter Table is searched for a matching entry, and the
remotely-initiated Process is either permitted to execute or is excluded from
execution. Because the local node is the SNODE for this type of transfer, it cannot
enforce the Process disposition setting in the NDMPXTBL parameter table. The
remote PNODE determines how the Process is handled. Typically, the remote node
places the Process in the Hold queue with a status of “HE” (Held in Error).
You can create or update the parameter table file while the server is active. Any
changes made to the file take effect for sessions that begin after the changes are
made.
Procedure
1. To modify the sample NDMPXTBL parameter table supplied with Sterling
Connect:Direct for Microsoft Windows, open any text editor.
2. Change the table using the following commands.
SACTQ0ACD@*—Matches ID
ACTQ0ACD from all nodes
3. When you update the parameter table, name it NDMPXTBL and save it to the
Server directory of the installation.
In this example, Sterling Connect:Direct executes all Processes that start with ACH
or are named DITEST01 or DITEST02. All other Processes are placed in the Hold
queue.
In this example, Sterling Connect:Direct does not execute any Process that starts
with ACH or is named DITEST01 or DITEST02. All other Processes are executed.
In this example, Sterling Connect:Direct executes all Processes that match one of
the following criteria:
v The specific secondary node (SNODE) name is DI.NODE1
v An SNODE whose name starts with DI0017
v Any Sterling Connect:Direct submitter ID from node DI0049
v The specific Sterling Connect:Direct submitter ID SACHAPP from any node
All Processes not matching one of the above criteria are flushed from the queue.
In this example, no Processes will not be executed, and a non-zero return code will
be displayed, which signifies an error along with message ID LPRX003E. The
remainder of the table is ignored (including the “F” code to flush Processes from
the queue), and all Processes are placed in the Hold queue.
Note: Secure+ is used to secure FASP transfers exactly the same way it is used for
TCP/IP transfers.
Related concepts:
“Using Sterling Connect:Direct for Microsoft Windows with IBM Aspera
High-Speed Add-on and Sterling Secure Proxy” on page 190
You can send files using IBM Aspera High-Speed Add-on through Sterling Secure
Proxy using Sterling Connect:Direct for Microsoft Windows.
Activating FASP
By default, IBM Aspera High-Speed Add-on for Connect:Direct is not enabled. To
enable it, you must download a license key and install Sterling Connect:Direct for
Microsoft Windows V4.7.0, Fix Pack 4 or later.
You must have Sterling Connect:Direct for Microsoft Windows V4.7.0 or later
installed.
Procedure
1. Download and install Sterling Connect:Direct for Microsoft Windows V4.7.0, Fix
Pack 7 or later from IBM Fix Central.
2. Download the IBM Aspera High-Speed Add-on for Connect:Direct license key
for your Connect:Direct node from Passport Advantage.
3. Rename the file aspera-license.
4. Save the renamed file to the <install_dir>\ConnectDirectvx.x.x\Server
directory.
What to do next
When both sender and receiver only have Endpoint licenses, file transfer over
FASP is not supported. When either the sender or receiver has an Endpoint license
and the other has a Datacenter license, the available bandwidth is limited to the
value in the Datacenter license. When both sender and receiver have Datacenter
licenses, the bandwidth is limited to the smaller of the two values in the
Datacenter licenses.
FASP is supported in Sterling Secure Proxy V3.4.3 or later. If you send a file from
your local Sterling Connect:Direct for Microsoft Windows node configured for
FASP, it passes through your Sterling Secure Proxy instance using FASP, and is sent
to the remote node.
The first parameter is the default for Connect:Direct as the PNODE. The second
parameter is the default for Connect:Direct as the SNODE.
This parameter can now be used in the netmap local node record and remote node
trading partner record in Connect:Direct for Windows.
The following table shows results when Connect:Direct FASP protocol is used
between two Connect:Direct nodes with no Sterling Secure Proxy involved.
The following table shows results when Connect:Direct FASP protocol is used with
two Connect:Direct nodes going through a single instance of Sterling Secure Proxy.
The following table shows results when Connect:Direct FASP protocol is used with
two Connect:Direct nodes going through two instances of Sterling Secure Proxy.
For more information on using Sterling Secure Proxy with FASP, see Using FASP
with IBM Sterling Secure Proxy (V3.4.3 or later).
Configuring FASP
About this task
Procedure
1. From the Admin Tool initialization parameters, click the TCP/IP tab.
2. In the Configure FASP section, click Properties.
Chapter 4. Using FASP with IBM Aspera High-Speed Add-on for Sterling Connect:Direct for Microsoft Windows (V4.7.0.4 or
later) 191
3. Configure the values for the Local Node by completing the following fields:
Field Value
FASP Listen Ports Type the port numbers you want to use for
FASP. Only valid for SNode configuration.
PNode FASP Flag Use when this is PNode. Valid values are:
v If set to Yes, use FASP on PNode
v If set to No, don't use FASP
v If set to SSP , use FASP with SSP bridging
v If set to Blank, use the default value of
No.
SNode FASP Flag Use when this is SNode. Valid values are:
v If set to Yes, use FASP on SNode
v If set to No, don't use FASP
v If set to SSP , use FASP with SSP bridging
v If set to Blank, use the default value of
No.
File Size Threshold Optional. Used to restrict small files from
being sent using FASP.
v If the file is greater than or equal to the
stated value, the Connect:Direct server
sends the file using FASP. Otherwise, it is
sent using TCP/IP.
v Default is 1GB.
v You can use KB, MB, or GB designators. If
no designator is included, the system uses
bits.
v This setting can be overridden by the
remote node record or process parameters.
Target Bandwidth Optional. Default is as stipulated in the
FASP license key. Specifies how much
bandwidth each transfer can use.
v Default value can be changed, but cannot
exceed the bandwidth specified in the
license key.
v You can use KB, MB, or GB designators. If
no designator is included, the system uses
bits per second.
v This setting can be overridden by the
remote node record or process parameters,
but cannot exceed the bandwidth
specified in the license key.
Field Value
Pnode FASP flag Use when this is PNode. Valid values are:
v If set to Yes, use FASP on PNode
v If set to No, don't use FASP
v If set to SSP , use FASP with SSP bridging
v If set to Blank, use the default value of
No.
Chapter 4. Using FASP with IBM Aspera High-Speed Add-on for Sterling Connect:Direct for Microsoft Windows (V4.7.0.4 or
later) 193
Field Value
SNode FASP Flag Use when this is SNode. Valid values are:
v If set to Yes, use FASP on SNode
v If set to No, don't use FASP
v If set to SSP , use FASP with SSP bridging
v If set to Blank, use the default value of
No.
File Size Threshold Optional. Used to restrict small files from
being sent using FASP.
v If the file is greater than or equal to the
stated value, the Connect:Direct server
sends the file using FASP. Otherwise, it is
sent using TCP/IP.
v Default is 1GB.
v You can use KB, MB, or GB designators. If
no designator is included, the system uses
bits.
v This setting can be overridden by the
process parameters.
Target Bandwidth Optional. Default is as stipulated in the
FASP license key. Specifies how much
bandwidth each transfer can use.
v Default value can be changed, but cannot
exceed the bandwidth specified in the
license key.
v You can use KB, MB, or GB designators. If
no designator is included, the system uses
bits per second.
v This setting can be overridden by the
process parameters, but cannot exceed the
bandwidth specified in the license key.
Optional Parameters
FASP Parameters:
v FASP (Yes | No)
v FASP POLICY (Values are the same as the FASP Local and Remote node record
parameters)
v FASP.FILESIZE.THRESHOLD (Values are the same as the FASP Local and
Remote node record parameters)
Chapter 4. Using FASP with IBM Aspera High-Speed Add-on for Sterling Connect:Direct for Microsoft Windows (V4.7.0.4 or
later) 195
v FASP.BANDWIDTH (Values are the same as the FASP Local and Remote node
record parameters)
FASP Parameters are applicable in three different contexts:
v COPY statement - The four FASP parameters may be used individually or as a
group within a COPY statement. This will set FASP values for the duration of
the COPY statement and will not have any effect on statements within the
submitted Process.
v PROCESS statement - The four FASP parameters may be used individually or as
a group at the end of a PROCESS statement. This will set the FASP parameters
for all of the COPY statements in the process
v SUBMIT command - The four FASP parameters may be set individually or as a
group at the end of a SUBMIT command. This will set the FASP parameters for
all COPY statements in the process being submitted These settings will set FASP
information for their relevant part of the scope, potentially overriding the Local
Node settings, Remote Node settings and each other.
Examples
FASP Messages
Use the following table to obtain FASP error message information.
Note: Long text message files for these message IDs can be viewed using the
Connect:Direct Requester Message Lookup utility.
Chapter 4. Using FASP with IBM Aspera High-Speed Add-on for Sterling Connect:Direct for Microsoft Windows (V4.7.0.4 or
later) 197
Non-Detailed Statistics Mode (Message ID
only) Detailed Statistics Mode
FASP032E FASP032E: FASP license in error.
FASP033E FASP033E: FASP license is malformed.
FASP034E FASP034E: FASP license is malformed.
FASP035E FASP035E: FASP License file at
&LOCATION will expire in &VALUE day(s).
FASP040E FASP040E: FASP initialization failed - remote
&TYPE &NODE. Error=&ERROR.
FASP041E FASP041E: FASP initialization failed - local
&TYPE &NODE. Error=&ERROR.
FASP042E FASP042E: FASP initialization failed.
Note: Some values might not be available. See “Known Limitations” for more
information.
FASP Y
FASP Listen Port 20014
FASP Filesize Threshold 1073741824
FASP Chunk Buffer size 16777216
Known Limitations
The following features cannot be used with FASP and Sterling Connect:Direct for
Microsoft Windows:
v Firewall navigation source ports should not be used with FASP
v Fasp bandwidth and policy negotiated values can be found in the
'aspera-stream-transfer.log' file. Submit a process and let the session complete. In
the aspera-stream-transfer.log file located in the <d_dir>\Server folder, search
for 'LOG FASP Session Parms':
2016-07-01 07:46:44 [2470-00001a70] LOG LOG FASP Session Params
uuid=1ea5dc66-4cca-4b3c-bf27-cd82eba733a3 userid=0 user="-"
targetrate=1000000000 minrate=0 rate_policy=fair
cipher=none resume=0 create=0 ovr=0 times=0 precalc=no mf=0 mf_path=- mf_suffix=-
partial_file_suffix= files_encrypt=no files_decrypt=no file_csum=none dgram_sz=0 prepostcmd=-
Chapter 4. Using FASP with IBM Aspera High-Speed Add-on for Sterling Connect:Direct for Microsoft Windows (V4.7.0.4 or
later) 199
200 Sterling Connect:Direct for Microsoft Windows 4.7: Documentation
Chapter 5. Secure Plus Option Implementation Guide
Overview
The Sterling Connect:Direct Secure Plus videos are useful for Sterling
Connect:Direct administrators. These tutorials provide a quicker way to access
information and remove the need to reference the Sterling Connect:Direct Secure
Plus documentation library.
Click the link below to access the Sterling Connect:Direct Secure Plus for Microsoft
Windows video channel to view tutorials about the following topics:
v Installation
v Configuration
v Troubleshooting
The Sterling Connect:Direct Secure Plus Microsoft Windows video channel can be
found at this link:Sterling Connect:Direct Secure Plus for Microsoft Windows Video
Channel.
Security Concepts
Cryptography is the science of keeping messages private. A cryptographic system
uses encryption keys between two trusted communication partners. These keys
encrypt and decrypt information so that the information is known only to those
who have the keys.
Sterling Connect:Direct Secure Plus enables you to select the security protocol to
use to secure data during electronic transmission: Transport Layer Security (TLS) or
Secure Sockets Layer protocol (SSL). Depending on the security needs of your
environment, you can also validate certificates using the IBM Sterling External
Authentication Server application.
To communicate using the SSL or TLS protocol, you must have both an X.509
certificate and a private key. The SSL and TLS protocols provide data security in
the following areas:
v Strong authentication—Because the CA went through an established procedure
to validate an applicant's identity, users who trust the CA can be sure the key is
held by the owner. The CA prevents impersonation, and provides a framework
of trust in associating an entity with its public and private keys.
v Proof of data origin and data integrity validation—The certificate provides proof
of origin of electronic transmission and encryption validates data integrity.
Encrypting the private key ensures that the data is not altered.
v Data confidentiality—Cipher suites encrypt data and ensure that the data
remains confidential. Sensitive information is converted to an unreadable format
(encryption) by the PNODE before being sent to the SNODE. The SNODE then
converts the information back into a readable format (decryption).
Both the SSL protocol and the TLS protocol manage secure communication in a
similar way. However, TLS provides a more secure method for managing
authentication and exchanging messages, using the following features:
v While SSL provides keyed message authentication, TLS uses the more secure
Key-Hashing for Message Authentication Code (HMAC) to ensure that a record
cannot be altered during transmission over an open network such as the
Internet.
v TLS defines the Enhanced Pseudorandom Function (PRF), which uses two hash
algorithms to generate key data with the HMAC. Two algorithms increase
security by preventing the data from being changed if only one algorithm is
compromised. The data remains secure as long as the second algorithm is not
compromised.
v While SSL and TLS both provide a message to each node to authenticate that the
exchanged messages were not altered, TLS uses PRF and HMAC values in the
message to provide a more secure authentication method.
v To provide more consistency, the TLS protocol specifies the type of certificate
that must be exchanged between nodes.
v TLS provides more specific alerts about problems with a session and documents
when certain alerts are sent.
The following is included in Secure Plus for NIST SP800-131a and Suite B support:
v Support TLS 1.1 and 1.2 with SHA-2 cipher suites
v Support for SP800-131a transition and strict modes
v Support for NSA Suite B 128 and 192 bit cipher suites and modes
v Support for IBM CMS Keystore
v Support migrating existing Secure+ certificates to the IBM CMS Keystore
v Support for JRE 1.7 SR1 iKeyman/iKeycmd utilities for certificate management.
Note: Only one instance of the Secure+ Admin Tool or the Secure+ CLI may be
used at a time because they access the same configuration file. Do not open these
tools at the same time or multiple copies of the same tool at the same time (two
instances of Secure+ Admin or two instances of Secure+ CLI). Only the user who
accessed the configuration file first will be able to save updates.
The Secure+ Admin Tool enables you to configure and maintain the Sterling
Connect:Direct Secure Plus environment. The Admin Tool is the only interface for
creating and maintaining the Sterling Connect:Direct Secure Plus parameters file;
operating system utilities and editing tools do not work.
Parameters File
The Sterling Connect:Direct Secure Plus parameters file contains information that
determines the protocol and encryption method used during security-enabled
Sterling Connect:Direct operations. To configure Sterling Connect:Direct Secure
Plus, each site must have a parameters file that contains one local node record and
at least one remote node record. The local node record defines the most commonly
used security and protocol settings for the node at the site. Each remote node
record defines the specific security and protocol used by a trading partner. You
create a remote node record in the Sterling Connect:Direct Secure Plus parameters
file for each Sterling Connect:Direct node that you communicate with.
For additional security, the parameters file is stored in an encrypted format. The
information used for encrypting and decrypting the parameters file (and private
keys) is stored in the Sterling Connect:Direct Secure Plus access file.
Access File
The Sterling Connect:Direct Secure Plus access file is generated automatically when
you create the Sterling Connect:Direct parameters file for the first time. You type a
passphrase when you first initialize Sterling Connect:Direct. This passphrase
encrypts and decrypts the private keys in the parameters file. Your administrator
must secure the access file. This file can be secured with any available file access
restriction tools. Availability of the access file to unauthorized personnel can
compromise the security of data exchange.
Sterling Connect:Direct Secure Plus uses two files to initiate TLS or SSL sessions: a
trusted root certificate file and a key certificate file.
Note: Sterling Connect:Direct Secure Plus does not support server gated crypto
(SGC) certificates.
v The trusted root certificate file verifies the identity of trusted sources who issue
certificates. To use Sterling Connect:Direct Secure Plus communication with a
trading partner, exchange trusted root file with the trading partner. The trading
partner must identify the trusted root file used to validate trusted sources in a
certificate when it configures its Sterling Connect:Direct Secure Plus parameters
file.
v A key certificate file is required at all sending locations and describes the
identity of the secure node. This file includes information about the certificate
being exchanged and the private key that defines the server.
When a trading partner attempts to establish communications with a Sterling
Connect:Direct node, the node sends the public key certificate to the trading
partner to verify its identity. The location of the key certificate file is configured
in the Sterling Connect:Direct Secure Plus parameters file. The private key in the
key certificate file is never sent (disclosed) by Sterling Connect:Direct.
The following list summarizes the tasks to configure Sterling Connect:Direct Secure
Plus:
v Populate the parameters file at your site by importing the Sterling
Connect:Direct network map. This task creates a local node record and remote
node records.
v Enable the TLS or SSL protocol in the local node record. Enabling the local node
record configures remote nodes to default to the settings in the local node
record. To enable TLS or SSL, activate the following options:
– Identify the trusted root certificate file that authenticates the trusted
authorities.
– Identify the key certificate file.
If you identify the trusted root file and the key certificate file to use for secure
communications in the local node record, the trusted root file must define the
identity of all CAs for all trading partners, and the root certificate associated
with the key certificate file must include certificate and private key
information for all certificates.
– Identify a cipher suite to use to encrypt data in both the sending and
receiving node. After secure communication is established, Sterling
Connect:Direct Secure Plus determines what cipher has been defined at both
Authentication
This guide assumes knowledge of the Sterling Connect:Direct system, including its
applications, network, and environment. If you are not familiar with Sterling
Connect:Direct, refer to the Sterling Connect:Direct library of manuals.
Task Overview
The following table directs you to the information required to perform the tasks
documented in the Sterling Connect:Direct documentation:
You can install Sterling Connect:Direct Secure Plus using theSterling Connect:Direct
for Microsoft Windows installation script. For more information on installing
Sterling Connect:Direct Secure Plus, see the IBM Sterling Connect:Direct for Microsoft
Windows Getting Started Guide.
CAUTION:
After Sterling Connect:Direct Secure Plus is installed, the system administrator
is responsible for securing access to the Sterling Connect:Direct Secure Plus
Administration Tool, Sterling Connect:Direct Secure Plus CLI, and parameters
files. The Sterling Connect:Direct Secure Plus administrator and Sterling
Connect:Direct server need full access to the Sterling Connect:Direct Secure Plus
directory. No other users require access.
Use the Secure+ Admin Tool to set up and maintain a Sterling Connect:Direct
Secure Plus operation.
You can also use the Sterling Connect:Direct Secure Plus Command Line Interface
(Secure+ CLI) to set up and manage Sterling Connect:Direct Secure Plus
operations. See “Start and Set Up the Sterling Connect:Direct Secure Plus CLI” on
page 219.
Note: The parameters file is not dynamically updated. When multiple users
update the parameters file, each user must close and reopen the file to display new
records added by all sources.
Procedure
1. Click Start > All Programs.
2. Select IBM Sterling Connect Direct v4.6.0 > CD Secure+ Admin Tool. The
Secure+ Admin Tool Main Window is displayed.
The Secure+ Admin Tool starts and opens the Sterling Connect:Direct Secure
Plus parameters file for the associated Sterling Connect:Direct node.
When you populate the parameters file from the network map, a record is
automatically created in the parameters file for each node entry in the network
map. Initially, Sterling Connect:Direct Secure Plus is disabled for each of the
records created. You configure the local node record to activate Sterling
Connect:Direct Secure Plus for all nodes in the parameters file.
Procedure
1. From the Secure+ Admin Tool Main Window, click File > Sync with Netmap.
The Available Netmaps dialog box is displayed.
2. Select the netmap to open and click Sync. The Select Netmap Entries to Add
dialog box is displayed.
3. Click Add All. The Select Parameters File Entries to Delete dialog box is
displayed.
4. Click Skip to close the parameters file without deleting any entries. The
Sterling Connect:Direct Secure Plus parameters file is populated and the
Secure+ Admin Tool Main Window displays remote node records in the
parameters file including the records you added from the network map.
Before performing your .Local node configuration, you need to import existing
certificates.
Procedure
1. Import existing certificates, either keycerts or trusted root files from trading
partners into the Key Store. On the Secure+ Admin Tool main window, from
the Key Management menu, select Configure Key Store. The Key Store
Manager window appears.
2. Verify the CMS Key Store path. If incorrect, click browseto locate the Key Store
path. The Browse CMS KeyStore File window appears.
3. The default Key Store name is: cdkeystore.kdb To locate the default Key Store
path, navigate to the Key Store file.
Windows path: <cdinstalldir>\Server\Secure+\Certificates\cdkeystore.kdb
Unix path: <cdinstalldir>/ndm/secure+/certificates/cdkeystore.kdb
4. Click Import. On the Import PEM KeyStore File window, navigate to and select
the certificate file you want to use and click OK.
5. If a key certificate file is being imported, the password must be entered. The
KeyStore Password window appears. Type your password and click OK.
6. The PEM Certificate Viewer displays to allow a review of the certificate file.
Verify the certificate is valid and click the Import button. Import Results
window displays with status of imported certificate. Click Close.
7. The certificate is imported and given a Label based on the certificate Common
Name, (CN=). Note the serial number to identify the correct certificate after
import.
Note: A common name is used for Label and identification which means that
multiple certificates can have the same common name and therefore, can be
overwritten depending on the setting of the Default Mode. Additionally, the
Default Mode of Import is Add or Replace Certificates.
8. Click OK to create the new CMS KeyStore file. Key Store Manager will display
contents of the new keystore.
Procedure
1. On the Key Store Manager window, click New. The Create new CMS KeyStore
File dialog box appears.
2. Enter the Directory location (you can also Browse to the location desired), the
KeyStore file name, and the password for the new KeyStore file. You can also
Note: A common name is used for Label and identification therefore multiple
certificates can have the same common name and therefore, can be overwritten
depending on the setting of the Default Mode. Additionally, the Default Mode
of Import is Add or Replace Certificates.
Before you can configure the .Local node record, you must either import your
existing certificates or create and configure a CMS Key Store. For additional
information, see Import Existing Certificates or Create CMS Key Store in the
documentation library.
It is recommended that you configure the .Local node record with the protocol
used by most of your trading partners. Because remote node records can use the
attributes defined in the .Local node record, defining the .Local node record with
the most commonly used protocol saves time. After you define the protocol in the
.Local node record, all remote nodes default to that protocol. Also, identify the
trusted root file to be used to authenticate trading partners.
To configure the local node, refer to the Local Node Security Feature Definition
Worksheet that you completed for the .Local node record security settings and
complete the following procedure:
Procedure
1. From the Secure+ Admin Tool Main Window, double-click the .Local record.
The Edit Record dialog box displays the Security Options tab, the node name,
and the type of node.
2. Set the Security Options for the local or remote node entry you are configuring
and if necessary, modify the time-out value in Authentication Timeout.
Refer to the following table for an explanation of the Security Options boxes:
3. Click the TLS/SSL Options tab. The TLS/SSL Options dialog box is displayed.
4. Select an existing Key Certificate from the key store. To select a Key Certificate
from the keystore, click Browse next to Key Certificate Label. The CMS
KeyStore Certificate Viewer appears.
Note: You must add or import the key certificate into your key store prior to
configuring your node. For additional information, see Import Existing
Certificates or Create CMS Key Store in the documentation library. For
additional information on how to use iKeyman, see http://www-01.ibm.com/
support/knowledgecenter/SSYKE2_6.0.0/
com.ibm.java.security.component.60.doc/security-component/
ikeyman_overview.html?lang=en.
5. In the Key Certificates area, select the key certificate you want to use and click
OK box.
6. Click the External Authentication tab. The External Authentication dialog box
is displayed.
7. Choose one of the following options:
v To enable external authentication on the remote node, click Yes in the Enable
External Authentication box.
v To disable external authentication on the remote node, click No.
8. Type the Certificate Validation Definition character string defined in Sterling
External Authentication Server.
9. Click OK to close the Edit Record dialog box and update the parameters file.
Before you can configure the .Remote node record, you must either import your
existing certificates or create and configure a CMS Key Store. For additional
information, see Import Existing Certificates or Create CMS Key Store in the
documentation library.
Configure the Remote node record with the protocol used by most of your trading
partners. Because remote node records can use the attributes defined in the Remote
node record, defining the Remote node record with the most commonly used
To configure the local node, refer to the Local Node Security Feature Definition
Worksheet that you completed for the Remote node record security settings and
complete the following procedure:
Procedure
1. From the Secure+ Admin Tool Main Window, double-click the .Remote record.
The Edit Record dialog box displays the Security Options tab, the node name,
and the type of node.
2. Set the Security Options for the local or remote node entry you are configuring
and if necessary, modify the time-out value in Authentication Timeout.
Refer to the following table for an explanation of the Security Options boxes:
3. Click the TLS/SSL Options tab. The TLS/SSL Options dialog box is displayed.
4. Select an existing Key Certificate from the key store. To select a Key Certificate
from the keystore, click Browse next to Key Certificate Label. The CMS
KeyStore Certificate Viewer appears.
Note: You must add or import the key certificate into your key store prior to
configuring your node. For additional information, see Import Existing
Certificates or Create CMS Key Store in the documentation library. For
additional information on how to use iKeyman, see http://www-01.ibm.com/
support/knowledgecenter/SSYKE2_6.0.0/
com.ibm.java.security.component.60.doc/security-component/
ikeyman_overview.html?lang=en.
5. In the Key Certificates area, select the key certificate you want to use and click
OK box.
6. Click the External Authentication tab. The External Authentication dialog box
is displayed.
7. Choose one of the following options:
v To enable external authentication on the remote node, click Yes in the Enable
External Authentication box.
v To disable external authentication on the remote node, click No.
8. Type the Certificate Validation Definition character string defined in Sterling
External Authentication Server.
9. Click OK to close the Edit Record dialog box and update the parameters file.
Perform this procedure to ensure that the nodes have been properly configured.
The validation process checks each node to ensure that all necessary options have
been defined and keys have been exchanged.
Procedure
1. In the Secure+ Admin Tool, click File > Validate Secure+. The Secure+ Admin
Tool - Validation Results window is displayed.
If the parameters file is not correctly configured, warning and error messages
are displayed.
2. Read each warning message. To correct each warning or error reported, go back
to the parameters file and make changes as needed.
Note: Warning messages do not always mean that the parameters file is
incorrectly configured. Some warning messages are informational only.
3. Click Close to close the Validation Results window.
On a node-by-node basis, you can specify whether a remote node uses external
authentication or if that remote node defaults to the external authentication setting
in the .Local node record.
Procedure
1. If necessary, open the remote node record. The Edit Record dialog box is
displayed.
2. Click the External Authentication tab.
3. Choose one of the following options:
v To enable external authentication on the remote node, click Yes in the Enable
External Authentication box.
v To disable external authentication on the remote node, click No.
v To default to the external authentication setting defined in the .Local node
record, click Default to Local Node.
Complete the following procedure to configure the server properties that will allow
Sterling Connect:Direct for Microsoft Windows to interface with Sterling External
Authentication Server:
Note: The values specified for this procedure must match the values specified in
Sterling External Authentication Server.
Procedure
1. Double-click the record called .SEAServer.
2. Type the Host Name for Sterling External Authentication Server.
3. Type the Port Number where Sterling External Authentication Server is
listening. The default is 61366.
4. Click OK to update the record.
Related concepts:
“Secure Sockets Layer Protocol (SSL) and Transport Layer Security Protocol (TLS)”
on page 202
Control Help
The Help command determines what help information is displayed. You can list all
the Sterling Connect:Direct Secure Plus CLI commands and display help for
individual commands.
Command Description
help Displays all the Sterling Connect:Direct Secure Plus CLI commands.
help <command> Displays help for the specified command.
Define the following commands to determine how error messages are captured:
Use LCU Files to Encrypt Passwords for Use with the Sterling
Connect:Direct Secure Plus CLI
The Sterling Connect:Direct Secure Plus CLI displays passwords in plain text. If
you are required to use encrypted passwords, use the Local Connection Utility
(LCU) to create an LCU file that contains non-encrypted information for encrypting
the password.
For more information on creating and using LCU files, see “Configure Encrypted
Passwords Using the LCU” on page 247.
Sample Scripts
The following script is provided as a model for creating custom scripts to define
your Sterling Connect:Direct Secure Plus environment and automate the
implementation of it. To prevent any loss of data, you cannot run the script, but
you can save it with a different name and modify it to suit your needs. The sample
script is available in Model Automation Scripts. The script is designed to assist you
as follows:
spcust_sample1.sh
Displaying Information
d_dir\Server\Secure+\Certificates\
ndm\secure+\certificates\
cdkeystore.kdb
Passphrase=The The retained password which was given
password for the at the creation of the keystore.
KeyStore file.
import keycert Imports existing File=Existing key Full path and filename to key certificate
keycerts into the certificate file. file to be imported.
keystore file.
*This file contains the
private key*
Passphrase=Password of Pre-defined password of key certificate
key certificate file to be file.
imported.
Label=(optional) Name A string of characters which can be an
of imported key alias name but if it is not defined, the
certificate file. Common Name of the certificate will be
the label used.
SyncNodes=Update y|n
node/certificate
references
ImportMode=Type of Add | Replace | AddOrReplace
import to be used.
import trustedcert Imports public File=Trusted public file Full path and filename to trusted
certificate files from from trading partner. certificate file to be imported.
trading partners.
The create remotenode command creates a remote node record and configures the
protocol settings. The command has the following parameters:
The update remotenode command creates a remote node record and configures the
protocol settings. The command has the following parameters:
The display remotenode command displays information about one or more remote
node records. The command has the following parameter:
Create Alias
The create alias command will create an alias record for an existing node record in
the Secure+ parmfile. The command has the following parameter:
The delete remotenode command deletes one or more remote node records. The
command has the following parameter:
Parameter Values
name=Name of the remote node remote node name | wildcard value
record to display information about.
To display information about more than one
Use wildcard characters to delete a remote node record, use wildcard characters.
group of remote node records.
Use wildcard characters to display information
about a group of remote node records. The options
are:
Update Password
SpeEnable=<Y>
;
If you enable or disable strong password encryption, the server displays the
following warning:
The Display Password command displays the strong password encryption setting.
The following table shows all the fields in the Node Name List:
.client
Type Displays the current record type. L—Local record
R—Remote record
Secure+ Displays the status of N—Disabled
TLS—TLS protocol
SSL—SSL protocol
Procedure
1. Open the Secure+ Admin Tool.
2. Click File > Info. The following fields are displayed in the File Information
dialog box.
Procedure
1. From the Secure+ Admin Tool Main Window, double-click the node record
name.
2. Click the Security Options tab.
The history of changes is displayed in the Update History field.
You can use this procedure to disable all nodes in a configuration or one remote
node.
Procedure
1. Do one of the following:
v To disable all nodes in a configuration, open the local node record.
v To disable one node, open the remote node record for that node.
2. Click the Security Options tab.
3. Click Disable Secure+.
4. Click OK to update the node record.
If a remote node record is no longer defined in the network map, you can remove
it from the parameters file. The following procedure deletes nodes that are defined
in the Sterling Connect:Direct Secure Plus parameters file but not in the selected
network map.
CAUTION:
Do not delete the remote node record that is named for the Sterling
Connect:Direct node. It is the base record for the .Local node record. You cannot
delete the .Local node record.
CAUTION:
Do not type a new passphrase if an error occurs. If an error occurs while you are
resecuring the files, restore the node records from the ACFSave directory. This
directory is created after the Rekey Secure+ feature is executed.
Procedure
1. From the Secure+ Admin Tool Main Window, click File > Rekey Secure+. The
Rekey Secure+ dialog box is displayed.
2. Type an alphanumeric string of at least 32 characters in the Passphrase field.
uses the passphrase to re-encrypt the Sterling Connect:Direct Secure Plus
parameters and access files. You do not have to remember this passphrase
value.
3. Click OK to accept the new passphrase. Sterling Connect:Direct Secure Plus
decrypts and re-encrypts the parameters file and access file.
View Statistics
View Statistics
Sterling Connect:Direct logs statistics for Sterling Connect:Direct Process activity.
The Sterling Connect:Direct statistics include Sterling Connect:Direct Secure Plus
information for a Process. Sterling Connect:Direct information is included in the
Process statistics information only when you attach to a Sterling Connect:Direct
server.
The Sterling Connect:Direct Secure Plus fields and valid values available using the
Select Statistics function of the Sterling Connect:Direct Requester are shown in the
following table:
When you use the CLI Select Statistics function to view the information about a
Sterling Connect:Direct Process, you see statistics information about a particular
Process. The Sterling Connect:Direct fields are shown in bold in the following
samples.
The following sample Session Start Record (SSTR) displays the output of an SSL
session:
The Copy Termination Record (CTRC) sample below uses the SSL protocol:
When you use the CLI select process command to view information about a
Sterling Connect:Direct Process, you see statistics about a Process. If Sterling
Connect:Direct Secure Plus is not enabled, no Sterling Connect:Direct Secure Plus
information is displayed:
Audits
The parameters file logging feature has the following operational characteristics:
v The logging feature is always enabled and cannot be disabled.
v If errors occur when the log is being updated, the application terminates.
v Each log entry contains a timestamp, user ID, and a description of the
action/event.
v When an existing node is updated, any changed fields are reported.
v When a node is created or deleted, the values of all non-empty fields are
reported.
v Any commands that modify a node are logged.
Note: The certificates used by Sterling Connect:Direct Secure Plus are individual
files that can be stored anywhere on the system. As a result, the logging feature
cannot detect when existing certificate files are modified. Sterling Connect:Direct
Secure Plus only stores the certificate path name and detects changes to this field
only.
The parameters file audit logs are stored in a dedicated directory, ..\secure+\log.
The log file naming convention is SP[YYYY][MM][DD].001 (using local time), and
the contents of a log file are limited to a single calendar date. You can view these
log files using any text editor. Log files are not deleted by Sterling Connect:Direct
Secure Plus.
[YYYYMMDD][HH:MM:SS:mmm][userid]
[YYYYMMDD][HH:MM:SS:mmm][userid][ParmFileID]
The following fields may appear in a create, update, or delete audit record.
Errors are reported for the following logging functions: open log, write log, and
lock log. If an error occurs during one of these functions, an error message is
displayed and the application is terminated. The lock function times out after 30
seconds. Typically, Secure+ Admin Tool or the CLI hold the lock for less than one
second per update.
In an SSL/TLS session, the PNODE (client) always logs the audit information. The
SNODE (server) only logs the information when client authentication is enabled.
For logging to occur, the session handshake must succeed and progress to the
point of logging the SSTR and CTRC records.
The audit consists of the subject name and serial number of the identity and its
signing certificate. The identity certificate also contains an issuer attribute, which is
identical to the signing certificate subject name. Although many signing certificates
may exist between the identity and final root certificate, the audit includes only the
last two certificates in a chain: an intermediate certificate and an end certificate.
In the SSTR and CTRC records, the CERT contains the common name and serial
number of the key certificate, and the CERI contains the common name of the
issuer and the serial number of an intermediate or root CA. They may also contain
the certificate serial number, for example:
CERT=(/C=US/ST=MA/L=Marshfield/O=test.org/OU=Dev/CN=Test ID/SN=99c0ce01382e6c83)|
CERI=(/C=US/ST=MA/L=Marshfield/O=test.org/CN=root CA/SN=da870666bbfb5538)
Certificate audit information located in the SSTR and CTRC records cannot be
accessed directly using Sterling Connect:Direct Requester or Sterling Connect:Direct
Browser User Interface. To access certificate information, you can issue a query
directly to the database or use an SDK-based or JAI-based program to issue a
Select Statistics command. The response to the Select Statistics command contains
the AuditInfo field of the statistics records, including the SSTR and CTRC records.
This field contains certificate audit information.
CERT=(MSGI=CSPA310E)|CERI=(MSGI=CSPA310E)
Troubleshooting
Use the following table to help troubleshoot problems with Sterling Connect:Direct
Secure Plus.
Configuration Worksheets
When you obtain a key certificate from a certificate authority, you have to add it to
a local key store file. To configure Sterling Connect:Direct Secure Plus, you have to
import a key certificate from the key store. Add the certificate label and common
name to the node record using the Secure Plus Admin Tool.
Use the IBM Key Management tool to add or delete certificate information in the
key store. In simple configurations, only one key store is used, but the key store
can contain multiple key certificates. The key store might also contain multiple
trusted root and intermediate certificates. Each certificate has a unique label to
differentiate them from one another. In more sophisticated configurations, you can
associate individual key certificate labels with one or more node records.
When you use a certificate signing request (CSR) tool, such as iKeyman, you do
not need to change the contents of the key certificate. This is created for you by
iKeyman.
Certificate Format
Procedure
1. In the Secure+ Admin Tool, click File > Validate Secure+. The Secure+ Admin
Tool - Validation Results window is displayed.
If the parameters file is not correctly configured, warning and error messages
are displayed.
2. Read each warning message. To correct each warning or error reported, go back
to the parameters file and make changes as needed.
To verify the success of the sample Process and review the Sterling Connect:Direct
Secure Plus statistics for the session, refer to Sterling Connect:Direct for Microsoft
WindowsGetting Started Guide.
Automation Scripts
REM
REM spcust_sample1.sh contains an example of configuring
REM Secure+ to use SSL or TLS protocols with the Secure+ CLI.
REM The example demonstrates the configuration of Secure+
REM with the trusted root and key certificates and ciphers
REM
REM
REM Variables
REM
pushd "%spDir%"
REM
REM Main script
REM
echo.
echo This script has been prevented from running because it will alter
echo The configuration of Secure+. Before removing this warning and its
echo exit call, please modify the script so that it carries out only
echo desired modifications to the configuration of Secure+.
echo.
goto :EOFc
all :initCustom
call :invokeCLI
call :terminateCustom
REM
REM Functions
REM
:initCustom
REM
REM Invoke CLI to configure Secure+.
REM
:invokeCLI
set tempFile=clicmds.txt
echo ; >>%tempFile%
echo display info >>%tempFile%
echo ; >>%tempFile%
echo ; >>%tempFile%
echo ; -- Synch with netmap >>%tempFile%
echo ; >>%tempFile%
echo sync netmap >>%tempFile%
echo path=v4.7.0\JLYON-LT >>%tempFile%
echo name=* >>%tempFile%
echo ; >>%tempFile%
echo ; >>%tempFile%
echo ; -- Import keycert and trusted cert files. >>%tempFile%
echo ; >>%tempFile%
echo import keycert >>%tempFile%
echo file="%spDir%\Certificates\keycert.txt" >>%tempFile%
echo passphrase=password >>%tempFile%
echo Label="My KeyCert"; >>%tempFile%
echo ; >>%tempFile%
echo import trustedcert >>%tempFile%
echo file="%spDir%\Certificates\trusted.txt" >>%tempFile%
echo ; >>%tempFile%
echo update localnode >>%tempFile%
echo override=n >>%tempFile%
echo protocol=(tls,tls1.1,tls1.2) >>%tempFile%
echo securitymode=FIPS140-2 >>%tempFile%
echokeycertlabel="My KeyCert" >>%tempFile%
echociphersuites=(TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA)
>>%tempFile%
echo ; >>%tempFile%
echo ; >>%tempFile%
echo ; -- Display localnode >>%tempFile%
echo ; >>%tempFile%
echo display localnode >>%tempFile%
echo ; >>%tempFile%
echo validate parmfile >>%tempFile%
echo ; >>%tempFile%
echo quit; >>%tempFIle%
REM
REM Custom termination logic written by customer.
REM
:terminateCustom
popd
LCU Files
The following example shows how to specify when an LCU file is used in place of
a plain-text password:
The use of the LCU syntax “LCU:” indicates that what follows is an LCU filename
and not a passphrase. The pathname of the LCU file can be a relative path, a
relative path to the bin directory, or a full path. If LCU:filename contains spaces, it
must be enclosed in quotation marks: “LCU:filename”. The default name of the
LCU file is cddef.bin. After the cddef.bin file is created, you can rename it as
needed.
LCU files can be used to provide encrypted passwords for the following
commands and parameters:
Command Parameter
Update LocalNode StsAuthKeyPairFilePassphrase
StsSigKeyPairFilePassphrase
SslTlsCertPassphrase
Create RemoteNode StsAuthKeyPairFilePassphrase
StsSigKeyPairFilePassphrase
SslTlsCertPassphrase
Update RemoteNode StsAuthKeyPairFilePassphrase
StsSigKeyPairFilePassphrase
SslTlsCertPassphrase
Create STSKeyPair Passphrase
Procedure
1. Type the following command to run the LCU utility:
lcu.bat
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
Or you may use the "/s" option to do so without bringing up a dialog box:
v regsvr32 /s "C:\Program Files\Sterling Commerce\Connect Direct
v4.7.0\SDK\CDSubmit.ocx"
v regsvr32 /s "C:\Program Files\Sterling Commerce\Connect Direct
v4.7.0\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.7.0\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
distributed with the application.
Two methods are available to create local node definitions. You can use either
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.
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:
v Adding a node
v Deleting a node
v Adding a user
v Deleting a user
v Updating node properties
v 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.
Procedure
1. Click Start > All Programs > IBM Sterling Connect:Direct > v4.7.0.
2. Select CD Client Connection Utility. The Client Connection Utility main
window is displayed.
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
About this task
Procedure
1. Select File > New Node. The Node Properties dialog box displays:
Note: Changes made to node settings are not written to the Registry until you
select Save.
Delete a Node
About this task
Procedure
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.
Add a User
About this task
Procedure
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.
Note: Changes made to node settings are not written to the Registry until you
select Save.
Delete a User
Procedure
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.
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.
Note: Changes made to node settings are not written to the Registry until you
select Save.
Procedure
1. Take one of the following actions:
v To define a default node, highlight the node.
v To define a default user, highlight the user.
2. Select Options > Set as Default to set the default node or user.
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.
Procedure
1. Select the node in which to import the Registry settings.
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.
Procedure
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.
Procedure
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.
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.
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.
Parameter Description
CdGetTraceFlags(unsigned int* Retrieves the current trace settings for the Sterling
pgrfTrace); Connect:Direct API.
CdSetTraceFlags(unsigned int Sets new trace settings for the Sterling Connect:Direct
grfTrace); API.
CdSetTraceFile(LPCTSTR Provides a file name to the tracing facility. If a file is
pszFilename); defined, trace messages are written to the Output
window and specified file.
Standard C API
Overview
The C API is implemented using the C++ Classes. This interface is used by C
programmers.
Note: You are responsible for closing the node handle and for releasing any
resources that you allocate.
v 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:
Blocking
Refer to the documentation CD directory, SDK\Samples for the C, C++, and Visual
Basic sample code. The sample code contains the following:
v The CSample1.C sample program demonstrates how to connect to a node,
execute a command, and view the data returned by the node.
v 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.
v CPPSamp1
v CPPSamp2
v VBAuto
v VBStat
v VBSubmit
v VBSubmit2
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.
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
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:
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:
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.
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, statistics,
messages, and users.
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.
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.
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.
CDSelectProcCmd cmd;
CDProcIterator it = cmd.Execute(node):
The iterator keeps an internal list of all records returned from the server. Use the
following commands to control iterator records:
v 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.
v 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.
CDSelectStatCmd cmd;
CDStatIterator it = node.Execute (cmd);
while (it.HasMore()) {
CDStatistic stat = it.GetNext();
// use the statistics object }
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.
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.
The Sterling Connect:Direct Logon dialog box does not perform the
logon. It captures the entries and returns them to the calling
program.
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.
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.
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
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. }
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.
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
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
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, Sets the symbolic value for symbolic. Call for each symbolic
value) in the Process.
ClearSymbolics Clears all symbolics. Call before submitting a Process to clear
the previous values.
Events
Events Description
Submitted Describes whether the Process is accepted by the server.
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_OUTOFMEMORY—out of memory.
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.
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 MicrosoftWindows 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.
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.
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.
eq | = | == Equal (default)
ne | != Not equal
SNMP — SNMP
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
Method Description
Complete Sent after all records are retrieved.
Error The standard error event. Possible codes are:
CTL_E_OUTOFMEMORY—out of memory.
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.
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.
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.
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:
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:
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.
To obtain a connection (and therefore a node), you must use the node factory.
Create the node factory using the ProgID 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.
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.
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.
Note: The usual Count property is not available because the count is not known
until all records are returned.
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.
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.
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.
See Changing Sterling Connect:Direct for Microsoft Windows Settings in the IBM
Sterling Connect:Direct for Microsoft Windows System Guide orIBM 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 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.
v userexit.h—Contains defined constants used for passtickets, the structures that
are passed to the passticket functions, and the function prototypes.
v 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.
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.
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.
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.
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.
v userexit.h
v FileOpenDLL.CPP
Structure Types
Structure Types
Following is a list of the common C and C++ Class interface structures, constants,
and their descriptions.
v NETMAP_DESC_STRUCT Structure
v USER_STRUCT Structure
v MESSAGE_STRUCT Structure
v NETMAP_MODE_SNA Structure
v NETMAP_MODE_TCP Structure
v NETMAP_NODE_STRUCT Structure
v NETMAP_PATH_STRUCT Structure
v PROCESS_STRUCT Structure
v NODE_STRUCT Structure
v STATISTICS_STRUCT Structure
v TRACE_STRUCT Structure
v 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.
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.
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.
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.
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 The message text.
[MAX_MESSAGE_TEXT+1]
MsgData Message substitution fields.
[MAX_MESSAGE_DATA+1]
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.
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.
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.
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.
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.
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.
Members
Member Description
ProcessName The Process name.
[MAX_PROCESS_NAME+1]
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.
Structure
struct Node_Struct
{
TCHAR Name[MAX_NODE_NAME_LEN+1];
TCHAR CDName[MAX_NODE_NAME_LEN+1];
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.
Structure
struct Statistic_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 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 The Process name.
[MAX_PROCESS_NAME+1]
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.
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.
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.
Return Codes
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.
Sample Programs
Sample source code projects help you understand how to use the .Net SDK. To run
the samples, place the CdCore.dll and ConnectDirectSdk.dll in your executable
path. You can copy these files to the same directory as the sample executables.
Procedure
1. Select Project >Add Reference from the menu.
2. Select Browse and search for the ConnectDirectSdk.dll file. Browse to the
C:\Program Files\Sterling Commerce\Connect Direct v4.7.0\SDK.Net\
Sdk_Files\Release location.
3. Highlight ConnectDirectSdk.dll and click OK.
4. Do one of the following to import the ConnectDirectSdk namespace:
v In Vb.Net, add the following command to your source modules:
Imports ConnectDirectSdk
v In C#.Net, add the following to your source modules:
Using ConnectDirectSdk
About Classes
Classes are provided to help configure your environment.
The Node class is the main interface to the Sterling Connect:Direct for Microsoft
Windows server. It contains the high-level Sterling Connect:Direct functions. Use it
to connect to a Node, submit Processes, and select statistics. Most access to the
Sterling Connect:Direct for Microsoft Windows server is through the Node object.
The Node object creates and removes the connection to the Sterling Connect:Direct
for Microsoft Windows server. Connections are shared and reused as different
requests are made.
The Process class allows you to retrieve information about Processes you submit or
that are in the TCQ. It contains all of the criteria returned from a Submit or
SelectProc method call.
The Statistic class allows you to retrieve statistic records from the TCQ. It
represents a group of records in the statistics database. They are returned from a
SelectStat method call.
During construction, the Node object tries to connect to the physical Sterling
Connect:Direct node, using the protocol information in the Registry. If the
connection fails, an exception is generated
In the following constructor, stNode is required. stUser and stPass are optional.
stPass is ignored if stUser is not provided.
In the following constructor, stLcuFile is required. This is the file spec for an LCU
file that contains the login information.
Node(String stLcuFile)
Disconnect Nodes
Use the DisconnectAll method to disconnect from all Nodes.
bool DisconnectAll()
Submit Processes
Use Submit and SubmitFile to submit Processes to a Node. These methods
automatically create a Process object and associate it with the Node for the Submit.
Below is the standard SubmitFile method. stFileName is required and is the file
specification of the Process to submit.
The Submit method is very similar to the SubmitFile method but instead of
passing the file name of the Process to submit, you pass stText which is the text of
a Process to submit.
void Submit(String stText, Hold holdOverride, String startTime, Dictionary<String, String> symbolics)
Manage Processes
The Node object provides several methods to manage Processes. You can view,
change and delete Processes, place a Process on Hold, or release it from Hold. Each
method returns Process information in the ProcessList property of the Node class
for each Process that was selected or changed.
The following SelectProc method allows you to retrieve a list of all Processes from
the TCQ:
void SelectProc()
The following SelectProc method retrieves Processes from the TCQ whose Process
number matches nNumber.
The following SelectProc method retrieves Processes from the TCQ whose Process
name matches any name in the array arrayNames.
The following SelectProc method retrieves Processes from the TCQ whose Process
number matches a number in arrayNumbers.
The following HoldProc method places a Process in the TCQ on HOLD. pProcess
is a Process object.
The following ReleaseProc method releases a Process from the HOLD and allows it
to run. pProcess is a process object.
The following DeleteProc method deletes a Process from the TCQ. pProcess is a
Process object.
The following DeleteProc method deletes a Process from the TCQ. nNumber is the
Process number to delete, stPNode is the primary node of the Process, and
stUserid is the User ID of the Process.
Note: The list could be large depending on how many days of records are kept in
the database.
void SelectStat()
The following SelectStat method retrieves all statistic records for a specific Process.
pProcess is the Process object to retrieve the stats for.
The following SelectStat method retrieves all statistic records within a specified
time range. dtBegin identifies the beginning time and dtEnd is the ending time.
The time is in the format MM/DD/YYYY hh:mm:ss AM|PM.
Node Properties
Following are the node properties returned:
v ApiVersion - API version of the node as a long
v CDName - Sterling Connect:Direct node name sent to the client after
successfully logging on
v Name - Alias node name passed in the constructor
v OSSubType - Operating system sub-type (additional information) of the node
v OSType - Operating system type of the node
v ProcessEntry - Process from a Submit call
v ProcessList - Array of Processes
v SecurePlusSupported - Indicates if the node supports IBM Sterling
Connect:Direct Secure Plus
v SecurePlusVersion - Sterling Connect:Direct Secure Plus version as a long
v Server - File server name where the Sterling Connect:Direct node is running
v StatsList - Array of Stat messages from a SelectStat call
v Userid - User ID used to log in to the node
Process Class
The Process class contains Process criteria returned from a SUBMIT or SELECT
PROCESS method. Processes are submitted using the Node.Submit or
Node.SubmitFile method.
void WaitForCompletion()
The following WaitForCompletion method blocks the current thread until the
Process exits all queues on the Sterling Connect:Direct server, including error
queues, or until the timeout period expires. timeout is in milliseconds.
Process Properties
Following is a list of the Process properties:
v ByteCount - Returns the Bytes read from the file as a long
v Checkpoint - Returns the Checkpointing Enabled flag
v Class - Returns the session class property as a String
v ConditionCode - Returns the Return Code as an int
v DestDisp1 - Returns the Destination file disposition parameter 1 as a char
v DestDisp2 - Returns the Destination file disposition parameter 2 as a char
v DestDisp3 - Returns the Destination file disposition parameter 3 as a char
v DestFile - Returns the Destination File Name as a string
v ExecPriority - Returns the Current Execution Priority as a String
v ExtendedCompression - Returns the Extended Compression flag
v Feedback - Returns the Additional Return Code Information as an int
v FromNode - Returns the From Node flag
v Function - Returns the Current Function Executing as a string
v Hold - Returns the Hold flag as a char
v LocalNode - Returns the Local Node indicator flag
v LogDateTime - Returns the Logged Timestamp
v MsgData - Returns the Message Substitution Data as a string
v MsgId - Returns the Message Identifier field as a string
v MsgText - Returns the Message Text field as a string
v Name - Returns the Process Name as a string
v Number - Returns the Process Number as an int
v PNode - Returns the Primary Node Name as a string
v Priority - Returns the Current Priority as in int
v Queue - Returns the Process Queue as a string
v RecordCount - Returns the Records read/written as a long
v Restart - Returns the Restart flag
v Retain - Returns the Retain flag as a char
v SchedDateTime - Returns the Scheduled Timestamp
v SecureEnabled - Returns the Sterling Connect:Direct Secure Plus enabled flag
v SecureProtocol - Returns the Sterling Connect:Direct Secure Plus Protocol as a
string
Statistic Class
The Statistic class represents a group of records in the statistics database. They are
returned by a SelectStat method call.
Audit Information
The GetAuditField method returns the value of the field requested from the Stats
Audit Information. Audit data in Stats records is optional and Stat records can
have different audit fields available. stField is the name of the audit field you
request information for; stValue is the value of the field requested. This method
returns TRUE if the audit field is found and FALSE if not.
Statistic Properties
Following are the statistics properties:
v ConditionCode - Returns the Return Code
v Feedback - Returns Additional Return Code information
v LogDateTime - Returns the Logged Timestamp
v MsgData - Returns the Message Substitution Data as a string
v MsgId - Returns the Message Identifier field as a string
v MsgText - Returns the Message Text field as a string
v ProcessName - Returns the Name of the process
v ProcessNumber - Returns the Process number
v RecCat - Returns the Record Category
v RecId - Returns the Record Identifier tag
v SNode - Returns the Secondary Node Name
v StartDateTime - Returns the Start Timestamp
v StopDateTime - Returns the Stop Timestamp
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 may use or distribute any of the information you provide 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:
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.
The performance data and client examples cited are presented for illustrative
purposes only. Actual performance results may vary depending on specific
configurations and operating conditions.
All IBM prices shown are IBM's suggested retail prices, are current and are subject
to change without notice. Dealer prices may vary.
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
fictitious and any similarity to actual people or business enterprises is entirely
coincidental.
COPYRIGHT LICENSE:
Each copy or any portion of these sample programs or any derivative work must
include a copyright notice as shown in the next column.
© 2015.
Portions of this code are derived from IBM Corp. Sample Programs.
© Copyright IBM Corp. 2015.
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.
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.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
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.
Notices 313
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.
Other company, product, and service names may be trademarks or service marks
of others.
Applicability
These terms and conditions are in addition to any terms of use for the IBM
website.
Personal use
You may reproduce these publications for your personal, noncommercial use
provided that all proprietary notices are preserved. You may not distribute, display
or make derivative work of these publications, or any portion thereof, without the
express consent of IBM.
Commercial use
You may reproduce, distribute and display these publications solely within your
enterprise provided that all proprietary notices are preserved. You may not make
derivative works of these publications, or reproduce, distribute or display these
publications or any portion thereof outside your enterprise, without the express
consent of IBM.
Rights
IBM reserves the right to withdraw the permissions granted herein whenever, in its
discretion, the use of the publications is detrimental to its interest or, as
determined by IBM, the above instructions are not being properly followed.
You may not download, export or re-export this information except in full
compliance with all applicable laws and regulations, including all United States
export laws and regulations.
Printed in USA