0% found this document useful (0 votes)

414 views

CDUnix UserGuide

User Guide to Connect: Direct for Unix.

Uploaded by

celia martinez

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

414 views

CDUnix UserGuide

User Guide to Connect: Direct for Unix.

Uploaded by

celia martinez

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 100

Sterling Connect:Direct for UNIX

User Guide
Version 4.1

Last updated: 17 September 2014

Sterling Connect:Direct for UNIX

User Guide
Version 4.1

Last updated: 17 September 2014

Note
Before using this information and the product it supports, read the information in Notices on page 85.

This edition applies to version 4.1 of IBM Sterling Connect:Direct and to all subsequent releases and modifications
until otherwise indicated in new editions.
Copyright IBM Corporation 1999, 2014.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.

Contents
Chapter 1. Controlling and Monitoring
Processes . . . . . . . . . . . . . . 1
Overview of the Command Line Interface . . .
Starting the CLI . . . . . . . . . . .
Stopping the CLI . . . . . . . . . . .
CLI Commands . . . . . . . . . . .
CLI Job Control . . . . . . . . . . .
CLI History Commands . . . . . . . .
Overview of Sterling Connect:Direct Commands
Submitting a Process. . . . . . . . . .
Changing Process Parameters . . . . . .
Deleting a Process from the TCQ . . . . .
Removing a Process from the Execution Queue
Stopping Sterling Connect:Direct . . . . .
Viewing a Process in the TCQ . . . . . .
Monitoring Process Status in the TCQ . . .
Determining the Outcome of a Process . . .
Generating a Detailed Output Report for a
Process . . . . . . . . . . . . . .
Generating a Summary Report for a Process .
Running System Diagnostics. . . . . . .

. 1
. 1
. 1
. 1
. 3
. 4
. 4
. 6
. 13
. 15
17
. 18
. 19
. 22
. 26
. 34
. 34
. 35

Chapter 2. Process Queuing . . . . . 39

Overview of the Transmission Control Queue
Scheduling Sterling Connect:Direct Activity.
Progression of a Process Through the TCQ .
The Execution Queue . . . . . . .
The Wait Queue . . . . . . . . .
The Timer Queue . . . . . . . .
The Hold Queue. . . . . . . . .

.
.
.
.
.
.
.

39
39
40
41
42
43
43

Chapter 3. Sterling Connect:Direct

Utilities . . . . . . . . . . . . . . 45
Introduction to Translation Tables . . . . . .
Creating a Translation Table . . . . . . .
Compiling a Translation Table Using the ndmxlt
Utility . . . . . . . . . . . . . .
ExampleCreating a Translation Table . . .
ExampleModifying a Model Translation Table
Using Translation During File Transfer
Operations . . . . . . . . . . . .
Translation Table Error Messages . . . . .
Accessing Sterling Connect:Direct Messages . .
Message File Content . . . . . . . . .
Message File Record Format . . . . . . .
Displaying Message Text . . . . . . . .
Precompressing/Decompressing Files Using the
Standalone Batch Compression Utility . . . .
Special Considerations for Using the Standalone
Batch Compression Utility . . . . . . .
Using the Standalone Batch Compression Utility
ExamplePrecompress a Text File . . . . .
ExamplePrecompress a Text File With
Codepage Conversion . . . . . . . . .

Copyright IBM Corp. 1999, 2014

. 45
. 45
. 46
. 46
47
.
.
.
.
.
.

47
48
48
48
49
49

. 50
. 50
51
. 53

ExamplePrecompress a Binary File . . . . .

ExampleDecompress a Text File . . . . . .
Examplescsdacomp Command Help . . . .
ExampleDecompress a File on the Remote
Node During the Copy Step . . . . . . . .
ExampleSend Precompressed File to z/OS and
Storing It as Precompressed . . . . . . . .
Validate Configuration Files . . . . . . . . .
Configuration Reports . . . . . . . . . . .
Generating a Configuration Report on the Base
Installation . . . . . . . . . . . . .
Generating a Configuration Report on Sterling
Connect:Direct Secure Plus for UNIX . . . . .
Generating a Configuration Report on Sterling
Connect:Direct for SWIFTNet for UNIX . . . .

Chapter 4. Writing Custom Programs

Introduction to Writing Custom Programs . . . .
Compiling Custom Programs . . . . . . . .
Writing Custom C Programs. . . . . . . . .
Creating a Connection to Sterling Connect:Direct
Using ndmapi_connect() or ndmapi_connect_c() .
Terminating a Connection Using
ndmapi_disconnect() or ndmapi_disconnect_c() .
Receiving Responses Using ndmapi_recvresp() or
ndmapi_recvresp_c() . . . . . . . . . .
Sending a Command to Sterling Connect:Direct
Using ndmapi_sendcmd() or
ndmapi_sendcmd_c() . . . . . . . . . .
Writing Custom C++ Programs . . . . . . . .

53
53
54
54
54
55
55
56
57
58

61
61
61
63
64
65
66

71
72

Chapter 5. Writing User Exits . . . . . 77

User Exit Programs . . . . . . . . . . . .
User Exit Functions. . . . . . . . . . . .
Initializing Communications with exit_child_init()
or exit_child_init_c() . . . . . . . . . .
Waiting for a Message Using recv_exit_msg() or
recv_exit_msg_c() . . . . . . . . . . .
Passing a File Descriptor Using send_exit_file()
or send_exit_file_c() . . . . . . . . . .
Sending a Message to Sterling Connect:Direct
Using send_exit_msg() or send_exit_msg_c() . .
Overview of User Exit Messages . . . . . . .
Statistics Exit Message . . . . . . . . . .
File Open Exit Messages . . . . . . . . .
Security Exit Messages . . . . . . . . .
User Exit Stop Message . . . . . . . . .
Copy Control Block. . . . . . . . . . .
Exit Log Files. . . . . . . . . . . . . .

77
77
78
79
79
80
81
81
81
82
84
84
84

Notices . . . . . . . . . . . . . . 85
Index . . . . . . . . . . . . . . . 89

. 53

iii

Sterling Connect:Direct for UNIX: User Guide

Chapter 1. Controlling and Monitoring Processes

Overview of the Command Line Interface
The Command Line Interface (CLI) enables you to submit Sterling Connect:Direct
Processes and commands from a native command line environment. You can also
use the Sterling Connect:Direct Browser User Interface to perform some of these
tasks.

Starting the CLI

Procedure
1. If you have not defined the NDMAPICFG environment variable, type the
following command for the appropriate shell, where d_dir is the path to the
Sterling Connect:Direct subdirectory.
In the C shell:
% setenv NDMAPICFG d_dir/ndm/cfg/cliapi/ndmapi.cfg

In the Bourne or Korn shell:

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

2. Type the following command to invoke Sterling Connect:Direct CLI. Type

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

Stopping the CLI

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

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

Copyright IBM Corp. 1999, 2014

Option

Description

Value

-P

Identifies the custom string to

use at the command line
prompt.

text string
Up to 32 characters.

Sample Command
Entry
$ direct
-PNewPrompt
$ direct -PTest CD
on Medea

If the prompt string includes

spaces or special characters,
enclose it in single or double
quotation marks.
The prompt string can also be
specified in the ndmapi.cfg file.
If a prompt string is specified
on the command line and in
the ndmapi.cfg file, -P takes
precedence.
When the default prompt
(Direct) is overridden, the
new prompt string is shown at
the command line prompt and
in the welcome banner display.
-s

Suppresses standard output.

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

none

$ direct -s

-t n

Enables the CLI/API trace

option. The level number, n,
identifies the level of detail in
the trace output.

1|2|4

$ direct -t 4

Specify one of the

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

Sterling Connect:Direct for UNIX: User Guide

Option

Description

Value

Sample Command
Entry

-e nn

Defines the error level above

which the CLI automatically
exits. If the returned error code
is greater than the error level
specified, the CLI automatically
exits.

0 | 4 | 8 | 16

$ direct -e 16

Valid values in the

error level code are:
0Indicates successful
completion.

Use this command within shell

4Indicates warning.
scripts.
This parameter prevents
unwanted execution of
commands following a
command that generates an
error above the specified level.

8Indicates error.
16Indicates
catastrophic error.

When the CLI terminates, it

returns a UNIX exit code that
can be tested by the shell.
-n name

Identifies the host name of the

computer where the Sterling
Connect:Direct server (PMGR)
is running.
Note: Invoking direct with -p
or -n overrides the settings in
the ndmapi.cfg file.

Sterling Connect:Direct
host name

$ direct -n hostname

-p nnnnn

Identifies the communications

port number for the Sterling
Connect:Direct node.
Note: Invoking direct with -p
or -n overrides the settings in
the ndmapi.cfg file.

102465535. The format $ direct -p 2222

is nnnnn.

-x

Displays command input on

standard out. Use this
command when debugging
scripts.

none

$ direct -x

-r

Makes the Process number

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

none

$direct -r | grep
_CDPNUM_

-h

Displays command usage

information if a Sterling
Connect:Direct command is
typed incorrectly.

none

$ direct -h

-z

Appends a newline character

after a prompt.

none

$ direct -z

CLI Job Control

Sterling Connect:Direct enables you to switch the CLI Process between the
foreground and the background in shells that support job control. This capability

Chapter 1. Controlling and Monitoring Processes

enables you to edit the text of saved Processes, issue UNIX commands, and resolve
Process errors without exiting and reentering the CLI. Use the following
commands to switch the CLI Process:
v Press the suspend character (Control-Z) to stop or suspend the CLI Process.
v Issue the fg command to move the CLI Process to the foreground.
Note: If you experience problems with job control, contact your system
administrator for suggestions on additional UNIX commands to use.

CLI History Commands

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

Description

Repeat the last command one time.

!#n

Set the number of commands to store in the

history buffer. The default history buffer size
is 50 commands.

Repeat command number <n> in the history

buffer.

!<string>

Repeat command beginning with the string

<string>.

List the contents of the history buffer.

Overview of Sterling Connect:Direct Commands

You control and monitor Sterling Connect:Direct Processes using the following
commands:
Note: The CMGR currently limits the size of a Process file to 60K bytes.

Command

Abbreviation Description

submit

sub

Makes Processes available for execution.

change process

cha pro

Changes the status and modifies specific characteristics,

of a nonexecuting Process in the TCQ.

delete process

del pro

Removes a nonexecuting Process from the TCQ.

flush process

flush pro

Removes an executing Process from the TCQ.

stop

Stops Sterling Connect:Direct for UNIX and returns

control to the operating system.

select process

sel pro

Monitors both executing Processes and Processes

waiting for execution. You can specify the search criteria
and the form in which the information is presented.

select statistics

sel stat

Retrieves information from the statistics file. You can

specify the search criteria and the form in which the
information is presented.

view process

view pro

View a Process in the TCQ where the local node is the

Pnode. View process can only display Processes running
on the local node since only the Pnode has the
information required to display a Process.

Sterling Connect:Direct for UNIX: User Guide

Abbreviations for Common Sterling Connect:Direct Commands

The following table lists valid abbreviations for commonly used parameters for
Sterling Connect:Direct commands:
Parameter

Abbreviation

detail

det

quit

recids

rec

release

rel

pname

pnam, pna

pnumber

pnum

sunday

sun

monday

mon

tuesday

tue

wednesday

wed

thursday

thu

friday

fri

saturday

sat

today

tod

tomorrow

tom

Restricting the Scripts and UNIX Commands Users Can Execute

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

Sterling Connect:Direct Command Syntax

Use the same command syntax for commands typed at the CLI prompt or used as
the command text parameter for an ndmapi_sendcmd() function. Refer to User
Exit Programs on page 77, for details on function calls. The following conventions
are used when typing commands:
v When selecting a password or user ID, do not use Sterling Connect:Direct
keywords.
v Be aware that user names and file names are case sensitive.
v Type an individual command keyword in uppercase, lowercase, or mixed-case
characters.
v Terminate all commands with a semicolon (;).

Chapter 1. Controlling and Monitoring Processes

v When typing commands, type the entire command name or type the first three
characters or abbreviate specific parameters. Refer to Abbreviations for
Common Sterling Connect:Direct Commands on page 5for a list of
abbreviations.
v Do not abbreviate Process statements and parameters.
v File names, group names, user IDs, and passwords are variable length strings
and can be any length.
v A Sterling Connect:Direct node name is 116 characters long. The name of a
record in the netmap describing a remote node is typically the remote Sterling
Connect:Direct node name, but can be any string 1256 characters long. You can
also specify a remote node name as an IP address or hostname and a port
number or port name.

Generic Parameter Value

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

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

List Parameter Value

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

Submitting a Process
The submit command makes Processes available for execution and enables the
software to interpret the Process statements contained in the specified files.
Parameters specified in the submit command override the same parameters
specified on the Process statement. There are no required parameters. However, if
you do not specify a file name for the file parameter, the text of the Sterling
Connect:Direct Process must follow the submit command. Following are the
parameters for the submit command:
Parameter

Description

file

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

Sterling Connect:Direct for UNIX: User Guide

Values

Parameter

Description

Values

class

The node-to-node session on which a Process

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

1|n

crc

hold

Determines if crc checking is performed. This

parameter overrides settings in the
initialization parameter, the network map, and
the Process.
Note: The user must be assigned authority to
change the crc settings in the user authority
file.

A numeric value from 1 to the value of maximum

concurrent local node connections
(sess.pnode.max). The default value is 1. The
value cannot be greater than the maximum
number of local sessions with primary control.
on | off
onTurns on crc checking.
offTurns off crc checking. The default is off.

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

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

maxdelay

How long the submit command waits for the

submitted Process to complete execution. This
parameter is useful when the command is
issued by a shell script. When this parameter is
specified, the script waits until the Process
completes before it continues execution. The
return code of the Process is stored in the $?
variable if you are using the Bourne or Korn
shell and in $status variable if you are using
the C shell, which the shell script can use to
test the results of Process execution. If you do
not specify maxdelay, no delay occurs.

unlimited | hh:mm:ss | 0
unlimitedWaits until the Process completes
execution.
hh:mm:ssWaits for an interval no longer than
the specified hours, minutes, and seconds.
0Waits until the Process completes execution. If
you specify maxdelay=0, you get the same results
as when you specify maxdelay=unlimited.

If the time interval expires, the submit

command returns a warning status code and
message ID to the issuing Process or CLI/API.
The Process is not affected by the time interval
expiration and executes normally.
newname

A new Process name that overrides the name

in the submitted Process.

A name up to 256 characters long

Chapter 1. Controlling and Monitoring Processes

Parameter

Description

Values

notify

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

pacct

A string containing information about the

pnode accounting data up to 256 characters
PNODE. Enclose the string in double quotation
marks.

pnodeid

Security user IDs and passwords at the

PNODE. The pnodeid subparameters can
contain 164 alphanumeric characters.

id [, pswd]
idSpecifies a user ID on the PNODE.
pswdSpecifies a user password on the
PNODE.If you specify pnodeid, you must also
specify id. Identify the ID first and the pswd last.

prty

The priority of the Process in the Transmission

Control Queue (TCQ). A Process with a higher
priority is selected for execution before a
Process with a lower priority. The prty value
does not affect the priority during
transmission.

115, where fifteen is the highest priority. The

default is 10.

retain

Determines if Sterling Connect:Direct retains a

copy of the Process in the TCQ. Sterling
Connect:Direct assigns a Process number to the
Process when it is placed in the retain queue.
When the Process is run, the Process number
assigned to the retain Process is incremented
by one. For example, if the Process is assigned
the Process number of 1445 in the retain
queue, the Process number is 1446 when the
Process is executed.

yes | no | initial

If you specify a start time and set retain=yes,

the Process remains in the Timer queue in HR
status and is submitted at the appropriate
interval. For example, when
startt=(Monday,2:00), the Process runs each
Monday at 2:00 AM. When startt=(,1:00), the
Process runs daily at 1:00 AM. Sterling
Connect:Direct does not provide a way to run
a Process hourly. To do this, you must use the
UNIX cron utility.

yesSpecifies that the system retains the Process

in the Hold queue in HR status after execution.
noSpecifies that the system deletes the Process
from the TCQ after execution. This is the default.
initialSpecifies that the system retains the
Process in the Hold queue in HR status for
automatic execution every time the Process
Manager initializes.

If no start time is identified, you must issue a

change process command to release the
Process for execution. Do not code the startt
parameter when you specify retain=initial.
sacct

Specifies accounting data for the SNODE.

Setting this value in the submit statement
overrides any accounting data specified in
Process.

Sterling Connect:Direct for UNIX: User Guide

snode accounting data up to 256 characters.

Enclose the string in double quotation marks.

Parameter

Description

Values

snode

Identifies the name of the secondary node.

Setting this value overrides the snode value in
the Process statement. The snode parameter is
required either on the submit command or
Process statement.

name | host name | nnn.nnn.nnn.nnn or

nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn[;port
name | nnnnn]]
nameSpecifies the node name of the remote
node. The secondary node name corresponds to
an entry in the network map file.
host nameSpecifies the name of the host
computer where the remote Sterling
Connect:Direct node is running.
nnn.nnn.nnn.nnn or
nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn
Specifies the IP address of the remote node in
IPv4 or IPv6 format: nnn.nnn.nnn.nnn (IPv4) or
nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn
(IPv6).
[;port number |nnnnn]Identifies the
communications port. You can only use this
parameter with the host name or IP address
parameters. The nnnnn value is a decimal number
from 1,02465,535.

Chapter 1. Controlling and Monitoring Processes

Parameter

Description

Values

snodeid

Specifies security user IDs and security

passwords on the SNODE. The snodeid
subparameters can contain one or more
alphanumeric characters.

id [,pswd [,newpswd]]

If Sterling Connect:Direct finds that a Process

has no snodeid parameter or defines a
snodeid parameter and the initialization
parameter proxy.attempt is set to y, then any
password specified on the snodeid parameter
is ignored. A proxy user record is a remote
user record in the userfile.cfg, which
corresponds to the user name specified on the
snodeid parameter. If no proxy user record
exists, the snodeid parameter must contain a
valid user name and password for a UNIX
user who has a corresponding local user record
in the userfile.cfg file.
When proxy.attempt=n and no snodeid is
defined, Sterling Connect:Direct uses the
submitting ID and node to find a Remote User
Information record in the User Authorization
Information file. If Sterling Connect:Direct
cannot find a match, then that user cannot
send or receive files.
If the initialization parameters file parameter
proxy.attempt is set to y, users are not required
to specify a password for the snodeid
parameter. This capability enables the id
subparameter to contain a dummy user ID to
be used for translation to a local user ID on
the remote system. The use of a dummy user
ID offers improved security because neither the
sender nor the receiver are required to use an
actual user ID.
Reserved keywords cannot be used in the
snodeid field.

Sterling Connect:Direct for UNIX: User Guide

idSpecifies a user ID on the SNODE.

pswdSpecifies a user password on the SNODE.
If you specify id, you do not have to specify
pswd. This capability enables the id parameter to
contain a dummy ID to be used for translation to
a local ID on the remote system.
newpswdSpecifies a new password value. On
certain platforms, the user password changes to
the new value on the SNODE if the user ID and
old password are correct (refer to documentation
on the specific platform). If the SNODE is a UNIX
node, the password does not change.
If you specify pswd, you must also specify id. If
you specify newpswd, you must also specify
pswd. Type the values in the order of id, pswd,
and newpswd.

Parameter

Description

Values

startt

Identifies the date, day, and time to start the

Process. Sterling Connect:Direct places the
Process in the Timer queue in WS (Waiting for
Start Time) status. The date, day, and time are
positional parameters. If you do not specify
date or day, a comma must precede time.

[date | day] [,hh:mm:ss [am | pm]]

Do not code the startt parameter when you

specify retain=initial.

dateSpecifies 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, which indicates midnight.
The current date is the default.
daySpecifies the day of the week. Values are
today, tomorrow, yesterday, monday, tuesday,
wednesday, thursday, friday, saturday, and
sunday.
hh:mm:ss [am | pm]Specifies the time of day in
hours (hh), minutes (mm), and seconds (ss). You
can specify the hour in either 12- or 24-hour
format. If you use 12-hour format, then you must
specify am or pm. The default is the 24-hour
format. The default value is 00:00:00, which
indicates midnight. If you specify only the day
value, the time defaults to 00:00:00. This means
that if you submit a Process on Monday, with
monday as the only startt parameter, the Process
does not run until the following Monday at
midnight.

&symbolic
name 1
&symbolic
name 2
&symbolic
name n

Specifies a symbolic parameter assigned a

value. The value is substituted within the
Process when the symbolic parameter is
encountered.

variable string 1
variable string 2

variable string n
The value for the symbolic parameter must be
in double quotation marks if it is a keyword or The symbolic name cannot exceed 32 characters.
contains special characters. If you want to

reserve the double quotation marks when the
symbolic name is resolved in the Process,
enclose the double-quoted string in single
quotes, for example:
&filename = filename with spaces'
The symbolic name itself must not be a subset
of any other symbolic name. (You cannot have,
for example, a symbolic name called &param
and another symbolic name called &parameter
in the same Process.)

Chapter 1. Controlling and Monitoring Processes

Parameter

Description

Values

tracel

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

Example - Submit a Process That Runs Every Week

The following command submits the Process named payroll:
submit file=payroll retain=yes startt=monday pacct=1959,dept-27";

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

Example - Submit a Process with a Start Time Specified

The following command submits the Process named copyfil:
submit file=copyfil snode=vmcent startt=(01/01/2008, 11:45:00 am);

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

Example - Submit a Process with No File Value

The following command submits a Process without a file parameter value, but
with the Process statements typed at the CLI command prompt:
Direct> sub do_copy process snode=node1
step01 copy from (
file=data.data
pnode
)
to
(
file=b
snode
)
pend ;
Process Submitted, Process Number = 5

Sterling Connect:Direct for UNIX: User Guide

Example - Submit a Process and Turn On Tracing

The following command submits the Process named copy.cdp:
submit file=copy.cdp tracel=4 pnode;

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

Changing Process Parameters

The change process command modifies specified parameters for a nonexecuting
Process.
You specify the Processes to be changed by Process name, Process number,
secondary node name, and submitter.
You can change the class, destination node, and priority. You can place a Process
on the Hold queue or release a Process from the Hold queue by issuing a change
process command with either the release or hold=no parameter.
If you submit a Process with a startt parameter, Sterling Connect:Direct places the
Process on the Timer queue. If a Process fails, you can move it to the Hold queue
by specifying the change process command with hold=yes. Sterling Connect:Direct
then places the Process in the Hold queue in HO status. You can release the
Process for execution at a later time.
You can set tracing for an existing Process by setting the tracel parameter to 1, 2,
or 4. You can turn off tracing for a Process by setting trace1 to 0.
Specify at least one of the following search criteria parameters:
Parameter

Description

Value

pname

Locate the Process to be

changed by Process name.

name | generic | (list)

The Process name is limited

to 8 characters on Sterling
Connect:Direct for Microsoft
Windows and Sterling
Connect:Direct for z/OS.

nameSpecifies the Process name, up to

8 alphanumeric characters.
genericSpecifies a nonspecific value
for the Process name. This generic value,
containing pattern-matching characters,
evaluates to a list of zero or more pname
strings.
listSpecifies a list of Process names.
Enclose the list in parentheses, and
separate each value with a comma.

pnumber

Locate the Process to be

changed by Process number.
Sterling Connect:Direct
assigns the Process number
when the Process is
submitted.

number from 199,999 | (list)

numberSpecifies the Process number.
listSpecifies a list of Process numbers.
Enclose the list in parentheses, and
separate each value with a comma.

Chapter 1. Controlling and Monitoring Processes

Parameter

Description

Value

snode

Locate the Process to be

changed by the secondary
node name. This parameter
can be used to specify a
specific remote node, a
generic value for matching
remote node names (using
pattern matching), or a list of
multiple remote node names.

remote node specification | generic | (list)

The secondary node name

typically contains the 116
character remote Sterling
Connect:Direct node name,
but can be any string up to
256 alphanumeric characters
long. You can also specify a
remote node name as an IP
address or hostname and a
port number.
submitter

Locate the Processes to be

changed by the node
specification (the Sterling
Connect:Direct node name)
and user ID of the Process
owner. The character length
of this parameter is
unlimited.

remote node specificationIdentifies a

specific remote node name.
genericSpecifies a nonspecific value
for the remote node name. This generic
value, containing pattern-matching
characters, evaluates to a list of zero or
more remote node names.
listSpecifies a list of remote node
specifications. Enclose the list in
parentheses, and separate each value
with a comma.

(node specification, userid) | generic | (list)

node specification, useridSpecifies the
node specification (the Sterling
Connect:Direct node name) and user ID.
genericSpecifies a nonspecific value
for node specification and user ID. This
generic value, containing
pattern-matching characters, evaluates to
a list of zero or more node specifications
and user IDs.
listSpecifies a list of node specification
and user ID pairs. Enclose the list in
parentheses, and separate each value
with a comma.

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

Parameter

Description

class

Changes the node-to-node

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

Sterling Connect:Direct for UNIX: User Guide

Value

Parameter

Description

Value

hold

Moves the Process to the Hold yes | no | call

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

newsnode

Specifies a new remote node

name to assign to the Process.

prty

115, where 15 is the highest priority. If

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

release

Releases the Process from a

held state. This parameter is
equivalent to hold=no.

none

tracel

Changes the level of trace to

perform for a Process.

level = 0 | 1 | 2 | 4

If you identify the SNODE or

PNODE immediately after the
trace level definition, the trace
level is turned on for all
Processes submitted to and
from the node identified.

new remote node specification

levelSpecifies the level of detail

displayed in the trace output. The
default is 4.
0Terminates the trace.1Is the basic
level that provides function entry and
function exit.2 Includes level 1 plus
function arguments.4Enables a full
trace. Basic diagnostic information,
such as values of internal data
structures at key points in the
execution flow, are displayed.

The following command changes the remote node name for the Process named
cdproc to a new remote node, paris:
change process pname=cdproc newsnode=paris;

Deleting a Process from the TCQ

The delete process command removes a nonexecuting Process from the TCQ.

Chapter 1. Controlling and Monitoring Processes

You select the Process to delete by Process name, Process number, secondary node
name, submitter, or any combination of the search criteria parameters. Specify at
least one of the following search criteria parameters:
Parameter

Description

Value

pname

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

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

pnumber

snode

Identify the Process to delete

by Process number. Sterling
Connect:Direct assigns the
Process number when the
Process is submitted. Valid
Process numbers range from
199,999.
Identify the Process to delete
by the secondary node name.
This parameter can be used
to specify a specific remote
node, a generic value for
matching remote node
names (using pattern
matching), or a list of
multiple remote node names.
The secondary node name
typically contains the 116
character remote Sterling
Connect:Direct node name,
but can be any string up to
256 alphanumeric characters
long. You can also specify a
remote node name as an IP
address or hostname and a
port number.

submitter

number | (list)
numberSpecifies the Process number.
listSpecifies a list of Process numbers.
Enclose the list in parentheses, and separate
each value with a comma (,).
remote node specification | generic | (list)
remote node specificationIdentifies a
specific remote node name.
genericSpecifies a nonspecific value for the
remote node name. This generic value,
containing pattern-matching characters,
evaluates to a list of zero or more remote
node names.
listSpecifies a list of remote node
specifications. Enclose the list in parentheses,
and separate each value with a comma.

(node specification, userid) | generic | (list)

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

Sterling Connect:Direct for UNIX: User Guide

The following command deletes all nonexecuting Processes submitted by user ID

cduser on node dallas:
delete process submitter=(dallas, cduser);

Removing a Process from the Execution Queue

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

Description

Value

pname

Locate the Process to

remove by Process name.

name | generic | (list)

The Process name is

limited to 8 characters on
Sterling Connect:Direct
for Microsoft Windows
and Sterling
Connect:Direct for z/OS.

nameSpecifies the Process name, up to 8

alphanumeric characters.
genericSpecifies a nonspecific value for the
Process name. This generic value, containing
pattern-matching characters, evaluates to a list
of zero or more pname strings.
listSpecifies a list of Process names. Enclose
the list in parentheses, and separate each value
with a comma.

pnumber

snode

Locate the Process to

remove by Process
number. Sterling
Connect:Direct assigns the
Process number when the
Process is submitted.

number from 199,999 | (list)

Locate the Process to

remove by the secondary
node name. This
parameter can be used to
specify a specific remote
node, a generic value for
matching remote node
names (using pattern
matching), or a list of
multiple remote node
names.

remote node specification | generic | (list)

The secondary node

name typically contains
the 116 character remote
Sterling Connect:Direct
node name, but can be
any string up to 256
alphanumeric characters
long. You can also specify
a remote node name as
an IP address or
hostname and a port
number.

numberSpecifies the Process number.

listSpecifies a list of Process numbers. Enclose
the list in parentheses, and separate each value
with a comma.

remote node specificationIdentifies a specific

remote node name.
genericSpecifies a nonspecific value for the
remote node name. This generic value,
containing pattern-matching characters,
evaluates to a list of zero or more remote node
names.
listSpecifies a list of remote node
specifications. Enclose the list in parentheses,
and separate each value with a comma.

Chapter 1. Controlling and Monitoring Processes

Parameter

Description

Value

submitter

Locate the Processes to

remove by the node
specification (the Sterling
Connect:Direct node
name) and user ID of the
Process owner.

(node specification, userid) | generic | (list)

node specification, useridSpecifies the node
specification (the Sterling Connect:Direct node
name) and user ID.
genericSpecifies a nonspecific value for node
specification and user ID. This generic value,
containing pattern-matching characters,
evaluates to a list of zero or more node
specifications and user IDs.
listSpecifies a list of node specification and
user ID pairs. Enclose the list in parentheses,
and separate each value with a comma.

The flush process command has the following optional parameters:

Parameter

Description

Value

force

Forcibly terminates an executing

Process or terminates a Process
in an orderly fashion as the step
completes. This parameter is
useful if a Process is in the
executing state and waiting for
unavailable resources.

yes | no

hold

yesSpecifies to forcibly and immediately

terminate the Process. The SMGR also
terminates immediately.
noSpecifies to terminate the Process in an
orderly fashion as the step completes. The
SMGR closes the statistics file and then
terminates. This is the default.

Places the terminated Process in yes | no

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

The following command flushes all executing Processes named Rome from the
Execution queue:
flush process pname=rome force=yes;

The following command flushes all executing Processes on node alma submitted
by user ID jones:
flush process submitter=(alma, jones);

Stopping Sterling Connect:Direct

The stop command initiates an orderly Sterling Connect:Direct shutdown sequence
or forcibly terminates the software. After you run the stop command, no new
Processes are allowed to run and no new connections with remote systems are
established. Commands can be issued and users can sign on until the server
terminates.

Sterling Connect:Direct for UNIX: User Guide

You can specify the force, immediate, quiesce, or step parameters with the stop
command.
Note: The force parameter is required when running Sterling Connect:Direct with
the LU6.2 feature on any supported platform other than AIX.
Following are the parameters for the stop command:
Parameter

Description

force

Forcibly terminates Sterling Connect:Direct

and returns control to the operating system.

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.

quiesce

Runs all executing Processes to completion

before shutting down Sterling
Connect:Direct. No new Processes are
started. This is the default value.

step

Shuts down Sterling Connect:Direct after all

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

The following command forcibly terminates Sterling Connect:Direct and returns

control to the operating system:
stop force;

Viewing a Process in the TCQ

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

Chapter 1. Controlling and Monitoring Processes

Parameter

Description

Value

pname

Locate the Process to view

by Process name.

name | generic | (list)

The Process name is limited

to 8 characters on Sterling
Connect:Direct for Microsoft
Windows and Sterling
Connect:Direct for z/OS.

nameSpecifies the Process name, up to 8

alphanumeric characters.
genericSpecifies a nonspecific value for the
Process name. This generic value, containing
pattern-matching characters, evaluates to a
list of zero or more pname strings.
listSpecifies a list of Process names. Enclose
the list in parentheses, and separate each
value with a comma.

pnumber

queue

Locate the Process to view

by Process number. Sterling
Connect:Direct assigns the
Process number when the
Process is submitted.

number from 199,999 | (list)

Specifies the Processes to be

viewed by the specified
queue names.

all | exec | hold | wait | timer

numberSpecifies the Process number.

listSpecifies a list of Process numbers.
Enclose the list in parentheses, and separate
each value with a comma.

allSelects Processes from all queues. This is

the default.
execSelects Processes from the Execution
queue.
holdSelects Processes from the Hold queue.
timerSelects Processes from the Timer
queue.
waitSelects Processes from the Wait queue.

snode

View the Process by the

secondary node name. This
parameter can be used to
specify a specific remote
node, a generic value for
matching remote node
names (using pattern
matching), or a list of
multiple remote node names.
The secondary node name
typically contains the 116
character remote Sterling
Connect:Direct node name,
but can be any string up to
256 alphanumeric characters
long. You can also specify a
remote node name as an IP
address or hostname and a
port number.

Sterling Connect:Direct for UNIX: User Guide

remote node specification | generic | (list)

remote node specificationIdentifies a
specific remote node name.
genericSpecifies a nonspecific value for the
remote node name. This generic value,
containing pattern-matching characters,
evaluates to a list of zero or more remote
node names.
listSpecifies a list of remote node
specifications. Enclose the list in parentheses,
and separate each value with a comma.

Parameter

Description

Value

status

Specifies the Processes to be

viewed by Process status. If
you do not specify a status
value, information is
generated for all status
values.

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

Chapter 1. Controlling and Monitoring Processes

Parameter

Description

Value

submitter

Locate the Processes to view

by the node specification (the
Sterling Connect:Direct node
name) and user ID of the
Process owner. The length of
this parameter is unlimited.

(node specification, userid) | generic | (list)

node specification, useridSpecifies the node
specification (the Sterling Connect:Direct
node name) and user ID.
genericSpecifies a nonspecific value for
node specification and user ID. This generic
value, containing pattern-matching
characters, evaluates to a list of zero or more
node specifications and user IDs.
listSpecifies a list of node specification and
user ID pairs. Enclose the list in parentheses,
and separate each value with a comma.

The following command displays the specified Process number:

view process pnumber=1;

Monitoring Process Status in the TCQ

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

Description

Value

pname

Locate the Process to select

by Process name.

name | generic | (list)

The Process name is limited

to 8 characters on Sterling
Connect:Direct for Microsoft
Windows and Sterling
Connect:Direct for z/OS.

nameSpecifies the Process name, up to 8

alphanumeric characters.
genericSpecifies a nonspecific value for the
Process name. This generic value, containing
pattern-matching characters, evaluates to a
list of zero or more pname strings.
listSpecifies a list of Process names. Enclose
the list in parentheses, and separate each
value with a comma.

pnumber

Locate the Process to select

by Process number. Sterling
Connect:Direct assigns the
Process number when the
Process is submitted.

Sterling Connect:Direct for UNIX: User Guide

number from 199,999 | (list)

numberSpecifies the Process number.
listSpecifies a list of Process numbers.
Enclose the list in parentheses, and separate
each value with a comma.

Parameter

Description

Value

queue

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

selected by the specified
queue names. The default is allSelects Processes from all queues. this is
the default.
all.
execSelects Processes from the Execution
queue.
holdSelects Processes from the Hold queue.
timerSelects Processes from the Timer
queue.
waitSelects Processes from the Wait queue.

snode

Locate the Process by the

secondary node name. This
parameter can be used to
specify a specific remote
node, a generic value for
matching remote node
names (using pattern
matching), or a list of
multiple remote node
names.

remote node specification | generic | (list)

listSpecifies a list of remote node

The secondary node name
specifications. Enclose the list in parentheses,
typically contains the 116
and separate each value with a comma.
character remote Sterling
Connect:Direct node name,
but can be any string up to
256 alphanumeric characters
long. You can also specify a
remote node name as an IP
address or hostname and a
port number.

Chapter 1. Controlling and Monitoring Processes

Parameter

Description

Value

status

Specifies the Processes to be

selected by Process status. If
you do not specify a status
value, information is
generated for all status
values.

Sterling Connect:Direct for UNIX: User Guide

Parameter

Description

Value

submitter

Locate the Processes to

select by the node
specification (the Sterling
Connect:Direct node name)
and user ID of the Process
owner. The length of this
parameter is unlimited.

(node specification, userid) | generic | (list)

node specification, useridSpecifies the node
specification (the Sterling Connect:Direct
node name) and user ID.
genericSpecifies a nonspecific value for
node specification and user ID. This generic
value, containing pattern-matching
characters, evaluates to a list of zero or more
node specifications and user IDs.
listSpecifies a list of node specification and
user ID pairs. Enclose the list in parentheses,
and separate each value with a comma.

detail

Specifies the type of report

(short or detailed) that
Sterling Connect:Direct
generates for the selected
Processes.

yes | no
yesGenerates a detailed report.
noGenerates a short report. This is the
default.

The following command displays a short report for the specified Process number:
select process pnumber=9 detail=no;

Output from the command is displayed in the following table:

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

The following command displays a detailed report for the specified Process
number:
select process pnumber=9 detail=yes;

Output from the command is displayed in the following table:

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

=> 19:52:35
=> 05/22/1996

Schedule Time =>

Schedule Date =>

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

Chapter 1. Controlling and Monitoring Processes

Determining the Outcome of a Process

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

Description

Value

ccode

Selects statistics records

based on the completion
code operator and return
code values associated
with Step Termination.
You must specify the
return code.

operator, nn
operatorSpecifies the completion code operator.
Following are the valid completion code
operators:
eq or = or == (equal) This is the default.
ge or >= or => (greater than or equal)
gt or > (greater than)
le or <= or =< (less than or equal)
lt or < (less than)
ne or != (not equal)
The return code is the exit status of the UNIX
command or the Sterling Connect:Direct Process
or command.
nnSpecifies the return code value associated
with Step Termination.

destfile

Selects statistics based on

a destination file name.
This parameter can be
abbreviated as dest.

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

Sterling Connect:Direct for UNIX: User Guide

Parameter

Description

Value

pname

Locate the statistics to

select by Process name.

name | generic | (list)

The Process name is

limited to 8 characters on
Sterling Connect:Direct
for Microsoft Windows
and Sterling
Connect:Direct for z/OS.

nameSpecifies the Process name, up to 8

alphanumeric characters.
genericSpecifies a nonspecific value for the
Process name. This generic value, containing
pattern-matching characters, evaluates to a list of
zero or more pname strings.
listSpecifies a list of Process names. Enclose the
list in parentheses, and separate each value with
a comma.

pnumber

reccat

Locate the statistics to

select by Process number.
Sterling Connect:Direct
assigns the Process
number when the Process
is submitted.

number from 199,999 | (list)

numberSpecifies the Process number.
listSpecifies a list of Process numbers. Enclose
the list in parentheses, and separate each value
with a comma.

CAEV | CAPR | (CAEV, CAPR)

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

Chapter 1. Controlling and Monitoring Processes

Parameter

Description

Value

recids

Specifies the statistics file

records to be selected by
record ID. This parameter
identifies particular types
of statistics records, such
as a copy termination
records or Sterling
Connect:Direct
initialization event
records.

record id | (list)
record idSelects statistics file records for the
specified record ID.
listSpecifies a list of Process names. Enclose the
list in parentheses, and separate each value with
a comma.
Following are the valid record ID values:
APSMLicense Management failure generated.
CHFAChange Functional Authority command
issued.
CHGPThe change process command issued.
CHPXChange Proxy command issued.
CRHTCopyright statement.
COACListen connection enabled for either API
or a remote node.
CSPASterling Connect:Direct Secure Plus
failure generated.
CSPEStrong Password Encryption event.
CSTPChild Process stopped.
CTIMCommand Manager inactivity timer
popped.
CTRCCopy termination record.
CTRMChild Process terminated.
CUKNChild Process unknown status.
CXITChild Process exited.
DELPThe delete Process command issued.
DLFADelete Functional Authority command
issued.
DLPXDelete Proxy command issued.
FLSPThe flush Process command issued.
FMRVError occurred in function management.
information receive operation.
FMSDError occurred in function management.
information send operation.
GPRCError occurred while getting Process.

Sterling Connect:Direct for UNIX: User Guide

Parameter

Description

Value
IFEDThe if statement ended.
LIEXLicense expired.
LIOKListen okay.
LSEDLocal Process Step Ended.
LSSTThe record ID of a step on the local node.
LWEXLicense expires within 14 days.
NAUHNode Authorization check issued.
NINFSterling Connect:Direct information
generated at startup.
NMOPNetwork map file opened.
NMPRThe network map is updated through
Sterling Connect:Direct Browser User Interface,
Sterling Control Center Console, or KQV
Interface.
NUICInitialization complete.
NUISInitialization started.
NUTCTermination completed.
NUTSTermination started.
PERRProcess error.
PFLSProcess flushed.
PPERPipe Error.
PREDProcess ended.
PRINProcess interrupted.
PSAVProcess saved.
PSEDProcess Step Ended.
PSTRProcess started.
QCEXA Process moved from another queue to
the EXEC queue.
QCWAA Process moved from another queue to
the WAIT queue.
QCTIA Process moved from another queue to
the TIMER queue.
QCHOA Process moved from another queue to
the HOLD queue.
QERRTest Mode error event.
RFIPRefresh initparms command issued.

Chapter 1. Controlling and Monitoring Processes

Parameter

Description

Value
RJEDThe run job ended.
RNCFRemote node connection failed.
RSEDRemote Process Step Ended.
RSSTThe record ID of a step on the remote
node.
RTEDThe run task ended.
RTRSRun Task Restarted.
RTSYRun task restarted. Re-syncing with run
task that was executing.
SBEDThe submit ended.
SCNTMax session count.
SCPAStep end status.
SELMSelect message command issued.
SELPThe select Process command issued.
SELSThe select statistics command issued.
SENDSession ended.
SERRSystem error.
SFSZSize of the file submitted.
SGONUser signed on using KQV Interface or
Command Line Interface.
SHUDShutdown occurred.
SIGCSignal caught.
SLFASelect func. Authority command issued.
SLIPSelect initparms command issued.
SLNMSelect netmap command issued.
SLPXSelect proxy command issued.
SLSGSelect signature command issued.
SPACS+ cmd add key certificate.
SPATS+ cmd add trusted root certificate.
SPCLS+ cmd add alias node.
SPCNS+ cmd add node.
SPDNS+ cmd delete node.

Sterling Connect:Direct for UNIX: User Guide

Parameter

Description

Value
SPGCS+ cmd select ciphersuites.
SPRKS+ cmd rekey parmfile.
SPSCS+ cmd select key certificate.
SPSNS+ cmd select nodes.
SPSTS+ cmd select trusted root certificates.
SPSYS+ cmd sync netmap.
SPUCS+ cmd change key certificate.
SPUNS+ cmd change node.
SPUTS+ cmd change trusted root certificate.
SPVPS+ cmd validate parmfile.
SSTRSession start.
STOPThe stop command issued.
SUBPThe submit command issued.
SUBVValidate Process command issued.
TRACThe trace command issued.
TZDIThe time zone of the local node
represented as the difference in seconds between
the time at the local node and the Coordinated
Universal Time.
UNKNUnknown command issued.
USECSecurity check for user ID failed.
USMGSterling Connect:Direct is shutting
down.
VEWPView Process command issued.
Logged messages may not have an explicitly
defined record id. These messages default the
record id to the first four characters of the
message. Some examples are listed below.
XCMMCommand manager (CMGR) messages.
XCPRCopy receive.
XCPSCopy send.
XIPTCommunication errors.
XLKLLow-level TCQ record locking errors.
XMSGMessage sent to user exit.

Chapter 1. Controlling and Monitoring Processes

Parameter

Description

Value
XPACProcess parsing message.
XPAEParsing error occurred when a Process or
command was submitted.
XPAMParsing error occurred when a Process
or command was submitted.
XPMCProcess manager (PMGR) connection
error messages.
XPMLPMGR statistics log error messages.
XPMPPMGR error messages when checking
permission on the Sterling Connect:DirectSelect
programs.
XPMRPMGR RPC and miscellaneous error
messages.
XPMTPMGR termination error messages.
XRPMRun task or run job error messages.
XRRFRelative record file access error messages.
File structure is use for TCQ.
XSMGSession manager (SMGR) error
messages.
XSQFFile access error messages.
XSTAUser exit program started.
XTQGA single TCQ error message group.
XTQZA single TCQ error message group.

snode

Locate the statistics file

record by the secondary
node name. This
parameter can be used to
specify a specific remote
node, a generic value for
matching remote node
names (using pattern
matching), or a list of
multiple remote node
names.

remote node specification | generic | (list)

listSpecifies a list of remote node specifications.

Enclose the list in parentheses, and separate each
The secondary node name value with a comma.
typically contains the
116 character remote
Sterling Connect:Direct
node name, but can be
any string up to 256
alphanumeric characters
long. You can also specify
a remote node name as
an IP address or
hostname and a port
number.

Sterling Connect:Direct for UNIX: User Guide

Parameter

Description

Value

srcfile

Selects statistics based on

a source file name. This
parameter can be
abbreviated as srcf.

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

startt

Selects records produced

both at and since the
specified time. The date
or day and time are
positional. If you do not
specify date or day, a
comma must precede
time.

[date | day] [, hh:mm:ss [am|pm]]

dateSpecifies 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.
daySpecifies the day of the week. Values are
today, monday, tuesday, wednesday, thursday,
friday, saturday, and sunday.
hh:mm:ss [am | pm]Specifies the time of day
in hours (hh), minutes (mm), and seconds (ss).
You can specify the hour in either 12- or 24-hour
format. If you use 12-hour format, then you must
specify am or pm. The default is the 24-hour
format. The default value is 00:00:00, which
indicates midnight. If you specify only the day
value, the time defaults to 00:00:00.

stopt

Specifies that Sterling

Connect:Direct searches
for statistics records up to
and including the
designated date, day, and
time positional
parameters. If you do not
specify date or day, a
comma must precede
time.

[date | day] [, hh:mm:ss [am|pm]]

Chapter 1. Controlling and Monitoring Processes

Parameter

Description

Value

submitter

Locate the statistics

records to select by the
node specification (the
Sterling Connect:Direct
node name) and user ID
of the Process owner. The
character length of the
parameter is unlimited.

(node specification, userid) | generic | (list)

node specification, useridSpecifies the node
specification (the Sterling Control Center Select
node name) and user ID.
genericSpecifies a nonspecific value for node
specification and user ID. This generic value,
containing pattern-matching characters, evaluates
to a list of zero or more node specifications and
user IDs.
listSpecifies a list of node specification and
user ID pairs. Enclose the list in parentheses, and
separate each value with a comma.

detail

yes | no
Specifies the type of
report (short or detailed)
yesGenerates a detailed report.
that Sterling
Connect:Direct generates
for the selected Processes. noGenerates a short report. This is the default.

Generating a Detailed Output Report for a Process

You can use the select statistics command to generate a detailed report for a
Process. The following command generates a detailed report for Process number 9:
select statistics pnumber=9 detail=yes startt=(08/10/2008);

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

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

Generating a Summary Report for a Process

You can use the select statistics command to generate a summary report for a
Process. The following command generates summary statistics for Process number
9:
sel stat pnumber=9 detail=no startt=(08/10/2008);

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

Sample output that describes all Process steps in summary form is displayed in the
following table:
===================================================================================
SELECT STATISTICS
===================================================================================
P RECID LOG TIME
PNAME PNUMBER STEPNAME CCOD FDBK MSGID
----------------------------------------------------------------------------------P PSTR 08/10/2008 09:10:39
PR01 9
0
XSMG200I
P IFED 08/10/2008 09:10:44
PR01 9
0
XSMG405I
P CTRC 08/10/2008 09:10:44
PR01 9
0
XSMG405I
P IFED 08/10/2008 09:10:45
PR01 9
4
XSMG400I

Sterling Connect:Direct for UNIX: User Guide

P RTED 08/10/2008 09:10:45

PR01 9
0
XSMG400I
P IFED 08/10/2008 09:10:45
PR01 9
4
XSMG400I
P CTRC 08/10/2008 09:10:45
PR01 9
0
XSMG405I
P CTRC 08/10/2008 09:10:45
PR01 9
8
XSMG405I
P CTRC 08/10/2008 09:10:45
PR01 9
8
XSMG405I
===================================================================================

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

Running System Diagnostics

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

Description

Value

cmgr

To trace the Command

Manager.

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

Chapter 1. Controlling and Monitoring Processes

Parameter

Description

Value

comm

To trace the data sent to

and received from a remote
Sterling Connect:Direct
system within the Session
Manager. You can set this
trace independently from
or in conjunction with the
smgr trace.

level=0 |1 | 2 | 4

If you run both the comm

and smgr traces, trace
output for both traces is
directed to the file name of
the trace last specified.

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

pmgr

To trace the Process

Manager.

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

Sterling Connect:Direct for UNIX: User Guide

Parameter

Description

smgr

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

Managers created after
issuing the trace command. snode | pnode | tnode
Currently executing Session
file=name
Managers are unaffected.
If you run both the comm
and smgr traces, trace
output for both traces is
directed to the file name of
the trace last specified.

Value

levelSpecifies the level of detail displayed in

the trace output. The default is 4.
0Terminates the trace.1Is the basic level
that provides function entry and function
exit.2Includes level 1 plus function
arguments.4Enables a full trace that
provides basic diagnostic information, such as
values of internal data structures at key points
in the execution flow.
snodeSpecifies to trace only the SNODE
SMGR.
pnodeSpecifies to trace only the PNODE
SMGR.
tnodeIdentifies the node on which to
perform the trace. If you want to gather trace
information for more than one node, identify
more than one node in this parameter.
fileSpecifies the name of a file where the
trace output is directed. If you do not specify a
file name, the file is created in the Sterling
Connect:Direct working directory with the file
name SMGR.TRC. The length of the name
value is unlimited. The default file name is
SMGR.TRC.

The following sample trace command performs a level 2 trace on the Session
Manager for the node called ath3500ry and writes the output to the file Smgp.trc:
trace smgr pnode tnode=ath3500ry level=2 file=Smgp.trc;

A partial sample trace output is illustrated in the following section. A trace

identifies the Process ID and the function, the month and day, and the time in
microseconds. The first column contains the Process ID. Column two indicates the
month and day in the form of MM/DD. Column three indicates the time in the
form of HH:MM:SSSS. The last column indicates the function. An arrow pointing
to the right indicates the function was entered. An arrow pointing to the left
indicates the function was exited. Some of the functions are indented, which
indicates nesting. An indented arrow indicates that the function was called by the
preceding function.
indicates that the function was called by the preceding function.
===================================================================================
498
05/18 15:13:0104
cm_sendcmd_1 entered.
498
05/18 15:13:0206
-> ndm_error_destroy
<- ndm_error_destroy: ok
498
05/18 15:13:0506
-> ndm_error_create
<- ndm_error_create: ok
498
05/18 15:13:0708
ndm_cmds_free entered.
ndm_cmds_free exited.
498
05/18 15:13:0801
->ndm_parser_jdi
Chapter 1. Controlling and Monitoring Processes

498

05/18 15:13:0806

498
498

05/18 15:13:0916
05/18 15:13:0926

498
498
498

05/18 15:13:1116
05/18 15:13:1136
05/18 15:13:1155

-> ndm_error_create
<- ndm_error_create: ok
->Parser: SELPRO
->bldexp
<-bldexp: Null argument value,
don't add.
->bldexp
-> ndm_crit_comp
->compile
<-compile
<- ndm_crit_comp: Handle
<-bldexp: ok

.
.
.
===================================================================================

Sterling Connect:Direct for UNIX: User Guide

Chapter 2. Process Queuing

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

Definition

change process

Change the status and modify specific

characteristics of a nonexecuting Process in
the TCQ.

delete process

Remove a nonexecuting Process from the

Wait, Timer, and Hold queues.

flush process

Remove an executing Process from the

Execution queue.

select process

Monitor Processes in the TCQ, including

those Processes that are executing.

view process

View Processes in the TCQ.

Scheduling Sterling Connect:Direct Activity

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

Queue

Comments

None of the
scheduling
parameters specified

Wait

The Process remains in the Wait queue until

Sterling Connect:Direct establishes a session with
the remote node. After a session is established,
the Process moves to the Execution queue.

retain=yes

Hold

A copy of the Process executes once, unless you

specify a startt parameter value. Specify a day or
time or both for the Process to start.

retain=no

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

Copyright IBM Corp. 1999, 2014

Scheduling
Parameter

Queue

Comments

retain=initial

Hold

A copy of the Process remains in the Hold queue

and executes every time the Process Manager is
initiated.

retain=yes and
hold=no or hold=call

Hold

A copy of the Process remains in the Hold queue

to be executed when released.

hold=yes

Hold

You can execute the Process by specifying the

change process command with the release
parameter.

hold=no

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

parameters are
specified)

hold=call

Hold

The Process remains in the queue until the

remote node starts a session with the local node
or another Process starts a session with that
remote node.

startt

Timer

When the scheduled day or time occur, the

Process is moved to the Wait queue.

Each Process in the TCQ has an associated status value. Each status value has a
unique meaning that is affected by the logical queue in which the Process is
placed. Status values for each queue are shown in the tables in the following
sections. You can use the select process command to examine that status of
Processes in the TCQ. For example, the following command displays all Processes
in the TCQ with execution status:
select process status=EX;

Progression of a Process Through the TCQ

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

Sterling Connect:Direct for UNIX: User Guide

The Execution Queue

Processes are placed in the Execution queue after Sterling Connect:Direct connects
to the remote node. Processes normally come from the Wait queue, but also can be
placed in the Execution queue by a submit command with maxdelay=0 specified.
Processes in the Execution queue can be in execution (EX) status or pending
execution (PE) status. Processes with EX status are exchanging data between two
Sterling Connect:Direct nodes. Processes with PE status are waiting for Process
start messages to be exchanged between the local node and the remote node.
Processes usually have PE status assigned for a very short period of time.

Chapter 2. Process Queuing

After a Process successfully completes, it is automatically deleted from the

Execution queue. A flush process command with hold=yes moves a Process from
the Execution queue and places it in the Hold queue. When a session is
interrupted, the Process moves from the Execution queue to the Timer queue if
retry values are specified. If connection is not made before the retry values are
exhausted or if retry values are not specified, the action taken depends on the
conn.retry.exhaust.action parameter. By default, the Process moves to the Hold
queue.
The following table shows the status values for the Execution queue:
Element

Comment

Pending Execution is the initial queue status

when a Process is submitted with
maxdelay=0.

Execution status indicates that the Process is

executing.

The Wait Queue

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

Status

Comment

This status indicates the Process is ready to

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

This status indicates that the Process is in

retry status. The number of retries and
intervals between retries is specified in the
network map.

This status indicates the initial queue status

when a Process is submitted without a hold
or retain value. This Process is ready to
execute as soon as possible.

This status indicates that the Process is

waiting for the PNODE to continue the
session.

Sterling Connect:Direct for UNIX: User Guide

The Timer Queue

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

Comment

This status indicates that the Process is in

retry status. The number of retries and
intervals between retries is specified in the
network map.

This status indicates that the Process is

waiting for the PNODE to continue the
session.

Held Retain indicates that the Process was

submitted with retain=yes or retain=initial
specified and has already executed. The
Process can be released later by a change
process command with release specified.

This status indicates the Process is ready to

The Hold Queue

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

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

Status

Comment

Held for Call indicates that the Process was

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

Held Initially indicates that the Process was

submitted with hold=yes specified. The
Process can be released later by a change
process command with release or hold=no
specified.

Held due to error specifies that a session

error or other abnormal condition occurred.

Held by Operator indicates that a change

process hold=yes was specified.

Held Retain indicates that the Process was

submitted with retain=yes or retain=initial
specified and has already executed. The
Process can be released later by a change
process command with release specified.

Held for Suspension indicates that the

operator issued a flush process command
with hold=yes specified. The Process can be
released later by a change process command
with release specified.

Sterling Connect:Direct for UNIX: User Guide

Chapter 3. Sterling Connect:Direct Utilities

Introduction to Translation Tables
Sterling Connect:Direct translates data from one character set code to a different
character set code, such as from ASCII to EBCDIC, based on a character translation
table in the d_dir/ndm/xlate directory. Sterling Connect:Direct provides a default
character translation table for use during file transfer operations or you can modify
this table using the utility program called ndmxlt.

Creating a Translation Table

1. To create a translation table, either copy the file called /cd_dir/cdunix/ndm/
src/def_send.sxlt or /cd_dir/cdunix/ndm/src/def_recv.sxlt, where cd_dir is the
directory where Sterling Connect:Direct is installed, and rename it or modify
this file.
2. Use a text editor to add the new values to the table in the file you created.
3. Compile the updated file with the ndmxlt utility.
4. Replace the default translation table in the d_dir/ndm/xlate with the updated
table. Each table is 256 bytes long.
Following is a sample translation table:
# This file contains an example of defining an ASCII-to-EBCDIC translation table and
# then changing it to translate lowercase to uppercase.
#
# Define the ASCII-to-EBCDIC table.
offset=0
00 01 02 03 04 05 06 07 08 05 15 0B 0C 0D 0E 0F
10 11 12 13 3C 15 16 17 18 19 1A 1B 1C 1D 1E 1F
40 5A 7F 7B 5B 6C 50 7D 4D 5D 5C 4E 6B 60 4B 61
F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 7A 5E 4C 7E 6E 6F
7C C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6
D7 D8 D9 E2 E3 E4 E5 E6 E7 E8 E9 AD E0 BD 5F 6D
79 81 82 83 84 85 86 87 88 89 91 92 93 94 95 96
97 98 99 A2 A3 A4 A5 A6 A7 A8 A9 C0 4F D0 A1 7F
80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F
90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F
A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF
B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF
C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 CA CB CC CD CE CF
D0 D1 D2 D3 D4 D5 D6 D7 D8 D9 DA DB DC DD DE DF
E0 E1 E2 E3 E4 E5 E6 E7 E8 E9 EA EB EC ED EE EF
F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF
#
# Change the lowercase characters to uppercase.
offset=61
C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 D7
D8 D9 E2 E3 E4 E5 E6 E7 E8 E9

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

Copyright IBM Corp. 1999, 2014

Compiling a Translation Table Using the ndmxlt Utility

Before you begin
You can create or modify a translation table tailored to your requirements with the
ndmxlt utility program.
To invoke the ndmxlt utility, type the following command at the UNIX prompt:
$ ndmxlt -ssourcefile -ooutputfile [ -rradix] [ -ffiller] -mxlatefile

The parameters for the ndmxlt command are listed in the following table:
Parameter

Description

Values

-ssourcefile

The path and file name of the translation

table source file. If no value is specified,
input is read from STDIN.

Path and name of translation

table

-ooutputfile

The path and file name of the translation

table output file.

Path and name of translation

output file

-rradix

The radix or base of the source file input

data. All numeric values whether from
command line options or input data are
interpreted based on the radix setting.

x|d|o
xHexadecimal. This is the
default.
dDecimal
oOctal
The default is x.

-ffiller

A filler byte value. The entire table is

initialized to this value before the input
data is scanned and applied to the table.

Any keyboard character,

number, or special character,
plus control characters
entered using a preceding
slash.
For example, \0 is null.

-m

The path and file name of a model

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

Path and file name of the

model translation table

ExampleCreating a Translation Table

About this task
Perform the following steps to create a sample translation table that changes
lowercase characters to uppercase characters:

Procedure
1. Make a copy of the sample translation table located at cd_dir/ndm/src/
def_send.sxlt.
2. Open the new translation table with a text editor.

Sterling Connect:Direct for UNIX: User Guide

3. Add the following lines to the bottom of the table. It should look like the table
in Creating a Translation Table on page 45when you have added this
information.
#
# Change the lowercase characters to uppercase.
offset=61
C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 D7
D8 D9 E2 E3 E4 E5 E6 E7 E8 E9

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

5. Compile the new translation table using the following syntax:
ndmxlt -s../src/UpperCaseEBC.sxlt -oUpperCaseEBC.xlt

6. To use this translation table, add the following sysopts parameter to the copy
statement:
copy from file=filename
to
file=filename
sysopts=":xlate.tbl=pathname/UpperCaseEBC.xlt:"

ExampleModifying a Model Translation Table

About this task
Perform the following steps to modify a model translation table. This method,
when implemented, reads the model table and writes it to a new file. It then reads
the input data and makes changes to the table created.

Procedure
1. Create a file called FourLinesUpperCase.sxlt and add the following lines to the
file:
#
# Change the lowercase characters to uppercase.
offset=61
C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 D7
D8 D9 E2 E3 E4 E5 E6 E7 E8 E9

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

3. Type the following command to compile this file and create a translation table
called fourLineUpperCase.xlt:
ndmxlt -s../src/FourLineUpperCase.sxlt -oFourLineUpperCase.xlt -mdef_send.xlt

4. To use this translation table, add the following sysopts parameter to the copy
statement:
copy from file=filename
to
file=filename
sysopts=":xlate.tbl=pathname/FourLineUpperCase.xlt:"

Using Translation During File Transfer Operations

Translation is specified in the copy statement of a Sterling Connect:Direct Process.
You can use the default translation table or create a new table.
Translation is specified in the copy statement of a Sterling Connect:Direct Process.
You can use the default translation table or create a new table.
To use the default translation table, type the following copy statement:
copy from file=abc
to
file=xyz
sysopts=":xlate.tbl=yes:"

Chapter 3. Sterling Connect:Direct Utilities

To specify a customized table for data translation, include the following sysopts
subparameter in the copy statement, where pathname/filename identifies the
translation table:
copy from file=filename
to
file=filename
sysopts=":xlate.tbl=pathname/filename:"

Refer to the UNIX section of the IBM Sterling Connect:Direct Processes Web site
at http://www.sterlingcommerce.com/documentation/processes/
processhome.html for additional details concerning translation table specification
with a copy statement.

Translation Table Error Messages

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

Description

XXLT001I

Invalid directive

XXLT002I

Input file open error

XXLT003I

Model file open error

XXLT004I

Invalid filler value

XXLT005I

Invalid offset value

XXLT006I

Invalid radix value

XXLT007I

Invalid table value

XXLT008I

Table data out of bounds

Accessing Sterling Connect:Direct Messages

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

Message File Content

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

Sterling Connect:Direct for UNIX: User Guide

xxx is a 3-character Sterling Connect:Direct component identifier

nnn is a 3-digit decimal number
I is the standard, though not required, suffix

Message File Record Format

The following example shows the format of the message file record. Each record
can be up to 4K bytes long. Optional parameters and values are in brackets.
message id [long.text detailed message explanation] [mod.name issuing module name] short.text
message summary

Following are the parameters for the message file record:

Parameter

Description

Values

long.text

A string that explains the message in detail.

A text string

mod.name

The name of the source module issuing the

message ID.

Source module name

short.text

A summary of the message. This field is

required.

Summary message, up to
72 characters

The following example illustrates a sample message record for XCPS008I:

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

Displaying Message Text

Use the ndmmsg command to display text in the message file. You can display
both short and long text.
The following command illustrates the format for ndmmsg:
ndmmsg -f msgfname [-l | -s] msgid1 [msgid2 [msgid3 [...]]]

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

Description

-f

Specifies the name of the message file.

-l

Displays the long text of a message.

-s

Displays the short text of a message.

Following is a sample ndmmsg command:

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

Output from the command is displayed in the following example:

rc=&rc
fdbk=&fdbk
mod.name=NUCMRG00.C
func.name=ndmapi_sendcmd
Chapter 3. Sterling Connect:Direct Utilities

short.text=CMGR RPC call returns NULL

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

Precompressing/Decompressing Files Using the Standalone Batch

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

Special Considerations for Using the Standalone Batch

Compression Utility
Consider the following when you are using cdsacomp to precompress files:
v If you precompress a file with the cdsacomp utility, then you cannot specify any
compression options in your Sterling Connect:Direct Process when you copy that
file.
v You cannot specify data transformations (xlate, codepage, strip blanks, and so
on) when sending a precompressed file with :precompress=yes: sysopts (for
on-the-fly decompression). The following transformation options are available:
-x
-p
-s
-a
v If you precompress a file with the cdsacomp utility on a Sterling Connect:Direct
node, then you cannot specify a checkpoint interval in your Sterling
Connect:Direct Process if you decompress the file as it is received by the remote
node.
v When you are copying a precompressed file to z/OS without :precomp=yes: (for
deferred decompression):
The Copy operation must specify DCB information for the destination file.
The physical block size of the destination file on Sterling Connect:Direct for
z/OS must match the logical block size of the precompressed source file on
Sterling Connect:Direct for UNIX.
The logical block size of the source file defaults to 27920 unless overridden by
the -b parameter.

Sterling Connect:Direct for UNIX: User Guide

Using the Standalone Batch Compression Utility

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

Following are the parameters for the cdsacomp utility:

Parameter

Description

Values

-m

Specify which mode to use: precompress

or decompress. This argument is
required.

compress | decompress
The default is compress.

-i

Specify the input file to precompress or

decompress. This argument is required.

full or relative path of input file

-o

Specify the output file to save. If the

output file already exists, it is
overwritten. This argument is required.

full or relative path of output

file

-z

Use this option with -m compress to

level, window, memory
override default compression values. This
levelCompression level.
argument is optional.
The range is 19. The default
When decompressing, the values used
is 1.
during compression are used.
1Provides the least
compression, but is the
fastest.
9Provides the most
compression, but is the
slowest.
windowThe size of the
compression window and
history buffer. Increasing the
window increases the
compression, but uses more
virtual memory. The range is
915. The default is 13.
memoryThe amount of
virtual memory to allocate.
The range is 19. The default
is 4.
1Uses the least virtual
memory.
9Uses the most virtual
memory.

-x

Use this option to translate the file.

If this parameter is not specified, the file
is not translated.

full path to translate table file

| relative path to translate
table file

This parameter is mutually exclusive

with -codepage.

Chapter 3. Sterling Connect:Direct Utilities

Parameter

Description

Values

-p

Use this option to specify codepages for

file conversion. Default is no codepage
translation.

source codepage, destination

codepage

This parameter is mutually exclusive

with -xlate.
-d

Specify the datatype of the file.

text | binary | VB

When you use -m compress, the

datatype values result in the following:

The default is text.

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

-s

Specify the block size of the output file.

nnnnn

This parameter is valid only when you

specify -m compress for the
compression option.

The range is 409632760. The

default is 27920.

Use this option to strip trailing blanks.

y|n

This parameter is valid only when you

specify -d text for the datatype of the
file.

yyes
nno
The default is y.

Sterling Connect:Direct for UNIX: User Guide

Parameter

Description

Values

-a

Use this option to replace zero-length

records with a single, blank character.

y|n

This parameter is valid only when you

specify the following: -d text and -m
compress.

yyes
nno
The default is y.
Specify n if the data is
copied to an i5OS or
mainframe node.

-h

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

ExamplePrecompress a Text File

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

compress
text
source.file
compressed.file
/home/cd/ndm/xlate/def_send.xlt
y

ExamplePrecompress a Text File With Codepage Conversion

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

compress
text
zzz.txt
zzz.sac
EBCDIC-US,ASCII

ExamplePrecompress a Binary File

In this example, the source file is a binary file named source.file which is
precompressed into a destination file named compressed.file. Default settings are
used for parameters that are not specified.
cdsacomp -m compress
-d binary
-infile source.file
-outfile compressed.file

ExampleDecompress a Text File

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

Chapter 3. Sterling Connect:Direct Utilities

cdsacomp -m
-d
-i
-o
-x

decompress
text
compressed.file
dest.file
/home/cd/ndm/xlate/def_recv.xlt

Examplescsdacomp Command Help

Requesting a summary of cdsacomp command parameters and help options:
cdsacomp -h

ExampleDecompress a File on the Remote Node During the

Copy Step
The precomp=yes parameter is used when the file was compressed by the
cdsacomp utility prior to this Process. The file is transferred by this Process as a
pre-compressed file. It is then decompressed by special processing as it is received
on the remote node.
sample process snode=cdunix1
step01 copy
from
(
file=/home/cd/upload/compressed.file
sysopts=:precomp=yes:
pnode
)
to
(
file=/home/cd/download/decompressed.file
snode
disp=rpl
)
pend;

ExampleSend Precompressed File to z/OS and Storing It as

Precompressed
The precompressed file is copied to the z/OS node with PNODE sysopts of
datatype=binary. The destination file is not decompressed. The DCB settings of
the original precompressed file are preserved on the z/OS node. The specified
checkpoint interval will be used during the file transfer. The file can be
decompressed with the z/OS cdsacomp utility.
sample process snode=cdunix1
step01 copy
from
(
file=/home/cd/upload/compressed.file
sysopts=:datatype=binary:
pnode
)
chkpt=2M
to
(
file=upload.compressed.file
dcb=(blksize=27920, lrecl=0, dsorg=ps, recfm=u)
snode
disp=(new,catlg)
)
pend;

Sterling Connect:Direct for UNIX: User Guide

Validate Configuration Files

When you manually edit any of the five text-based Sterling Connect:Direct
configuration files, the Configuration Checking Utility (cfgcheck) enables you to
validate these files offline. The following files can be validated using this utility:
userfile.cfg, initparm.cfg, netmap.cfg, ndmapi.cfg, and sysacl.cfg.
Note: The Strong Access Control File (sysacl.cfg) will be validated only when the
user running the Configuration Checking Utility is a root user.
By default, cfgcheck is run with no arguments and attempts to find all five of the
configuration files in the current working directory. If all of the Sterling
Connect:Direct components are not installed, then some of the files will not be
found. For example, if the Command Line Interface (CLI) is installed but the
Sterling Connect:Direct server is not installed, only the ndmapi.cfg file will exist in
the installation directory. Therefore, only the ndmapi.cfg file will be validated.
When cfgcheck is run with no arguments, the utility will report that the other
configuration files were not found.
Note: Before you can execute cfgcheck, you must set the NDMAPICFG
environment variable. For more information, see Overview of the Command Line
Interface on page 1.
To invoke cfgcheck, type the following command at the UNIX prompt:
$ cfgcheck -t -h -f filename.cfg

The cfgcheck command has the following arguments:

Argument

Description

No arguments (default)

When no arguments are specified and the

cfgcheck utility is run by a non-root user, it
searches the cfg/ directory for the
following configuration files: initparm.cfg,
netmap.cfg, userfile.cfg, and ndmapi.cfg.
When a root user runs cfgcheck, the utility
also searches the SACL/ directory to locate
the sysacl.cfg file.

-h

Prints the help screen and exits.

-t

Turns on tracing and prints verbose debug

information.

-f filename.cfg

Specifies a configuration file name to

validate, where filename is the name of one
of the configuration files. You can specify
multiple -f arguments. When the -f
argument is used, cfgcheck will not
automatically search for other configuration
files from the file specified.

Configuration Reports
You can generate a report of your system information and Sterling Connect:Direct
configuration information using the Configuration Reporting Utility (cdcustrpt).
Configuration reports can be generated for the following Sterling Connect:Direct
components:
v Base installation of Sterling Connect:Direct
Chapter 3. Sterling Connect:Direct Utilities

v Sterling Connect:Direct Secure Plus for UNIX

v Sterling Connect:Direct for SWIFTNet for UNIX
During the Sterling Connect:Direct installation, cdcustrpt is installed in the
<installation>/etc/ directory.

Generating a Configuration Report on the Base Installation

Before you begin
When you use cdcustrpt to generate a report on the base Sterling Connect:Direct
installation, it reports the following types of system information:
v Name and other information of the operating system
v Space on file systems
v Virtual memory statistics
v Contents of the Sterling Connect:Direct installation directory
In addition to reporting system information, cdcustrpt invokes the Configuration
Checking Utility (cfgcheck) to validate the syntax of the five text-based
configuration files (if they are available and if the user has access to the files) and
to report on the contents of the configuration files. For more information on
cfgcheck, see Validate Configuration Files on page 55.
In this procedure, default values are computed by the utility based on the location
and name of the installed Sterling Connect:Direct and are provided in brackets [
]. Press Enter to accept the default values.
To invoke cducustrpt and generate a report of the base installation:

Procedure
1. Type the following command at a UNIX prompt:
% cdcustrpt

2. Type the full path where Sterling Connect:Direct is installed and press Enter.
3. Type the full path and name for the report that will be generated and press
Enter.
The report is generated in the location you specified, and any error messages
are displayed as shown in the following example:
% cdcustrpt
Enter full path of Connect:Direct destination directory:[/sci/users/jbrown1/cd40]:
Enter full path and name for this support report file:[/sci/users/jbrown1/cd40/etc/
cd.support.rpt]:
ls: /sci/users/jbrown1/cd40/ndm/SACL: Permission denied
cdcustrpt ended

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

Sterling Connect:Direct for UNIX: User Guide

###########################################################################
#######
Connect:Direct for UNIX 4.0.00 configuration report
#######
###########################################################################
Connect:Direct for UNIX Version 4000, Build 00, IBM/RS6000 AIX, Fix date:
01OCT2007
Install directory: /sci/users/jbrown1/cd40
Local Node name: jb_aix40
Report for: jbrown1
=========================================================
=====
Begin: Environment and system information
=====
=========================================================
System: AIX skyglass 3 5 00CE208E4C00
Disk usage:
Filesystem

512-blocks

Free %Used

Iused %Iused Mounted on

/dev/hd4

262144

64216

76%

2479

/dev/hd2

8126464

2708688

67%

37802

4% /usr

/dev/hd9var

262144

18448

93%

613

2% /var

/dev/hd3

786432

363600

54%

424

1% /tmp

/dev/fwdump

524288

507752

/dev/hd1

262144

216520

18%

167

524288

52168

91%

3688

6% /opt

121634816

13629040

89%

264984

15% /sci

/proc
/dev/hd10opt
/dev/fslv00

4% /

scidalnis01:/export/nis01 1677670392 512499192

1% /var/adm/ras/platform
1% /localhome
-

70%

/proc

-1% /home/nis01

Memory statistics:
System Configuration: lcpu=4 mem=3824MB
kthr
memory
page
faults
cpu
----- ----------- ------------------------ ------------ ----------r b
avm
fre re pi po fr
sr cy in
sy cs us sy id wa
1 1 400072 232777
0
0
0
0
0
0
4 1805 197 0 1 99 0

Generating a Configuration Report on Sterling Connect:Direct

Secure Plus for UNIX
If cdcustrpt detects the Sterling Connect:Direct Secure Plus directory in the
installation directory, <installation>/ndm/secure+/, it invokes the Sterling
Connect:Direct Secure Plus Command Line Utility (splicli.sh) to report on Secure+
parameters. If Sterling Connect:Direct Secure Plus is detected, you are prompted to
enter the path to the Sterling Connect:Direct Secure Plus parameters file (the
default location is provided in brackets [ ]), for example:
Enter full path of Secure+ parmfile
directory: [/sci/users/jbrown1/cd40/ndm/secure+/nodes]:

Chapter 3. Sterling Connect:Direct Utilities

The following example shows an excerpt from a sample report:

=====
Begin: Secure+ parameters
=====
=========================================
All secure+ nodes:
**************************************************************
*
Secure+ Command Line Interface
*
*
Connect:Direct for UNIX v4.0.00
*
*------------------------------------------------------------*
* Copyright (c) 1999, 2008 Sterling Commerce Inc.
*
* All Rights Reserved.
*
**************************************************************
SPCLI> display all;
name=.Local
baserecord=brown_aix38
type=l
protocol=tls
override=n
authtimeout=120
stsenablesig=n
stsenableautoupdate=n
stslimitexportversion=y
stsenableenc=y
stsencalgs=(ideacbc128,tdescbc112,descbc56)
stsauthlocalkey=0305.095A.44E3.BD87.F476.45E8.09B1.FCCA.45ED.67B0.01AD
stsprevauthkeyexpdatetime=
stssiglocalkey=0204.BABA.613D.2FA5.AAE6.0BD4.5847.B610.A17F.C7DD.0AA2
stsprevsigkeyexpdatetime=
ssltlsseaenable=n
seacertvaldef=
ssltlstrustedrootcertfile=/home/nis01/jbrown1/CertificateWizard/cert.crt
ssltlscertfile=/home/nis01/jbrown1/CertificateWizard/athena.selfsigned.keycert.txt
ssltlsenablefipsmode=n
ssltlsenableclientauth=n
ssltlsenablecipher=(TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA)
2007/10/19 14:27:37 parmfile upgraded: SPV4
2007/03/27 09:25:14 jbrown1
2007/03/22 09:54:55 jbrown1

Generating a Configuration Report on Sterling Connect:Direct

for SWIFTNet for UNIX
If cdcustrpt detects the SWIFTNet directory in the installation directory,
<installation>/ndm/SwiftNet/, it includes the contents of the CDSwiftnet.cfg file in
the report. Values for password parameters are replaced by a string of asterisks (*).
The following example shows an excerpt from a sample report:
====================================================================================
Begin: /sci/users/jbrown1/swift31/ndm/SwiftNet/Version3/cfg/CDSwiftnet.cfg
====================================================================================
===Content of /sci/users/jbrown1/swift31/ndm/SwiftNet/Version3/cfg/CDSwiftnet.cfg===
o
# Connect:Direct UNIX for SWIFTNet 3.1.00 configuration file.
#
[Directory.Info]
CD.HomeDir="/sci/users/jbrown1/swift31"
CDSwiftnet.HomeDir="/sci/users/jbrown1/swift31/ndm/SwiftNet/Version3"
# Concatenate the RequestorDN and ResponderDN to these directories for the Request
Handler.
Reception.Dir="/sci/users/jbrown1/reception"
Download.Dir="/sci/users/jbrown1/download"
# This directory must be specified to use the #OLDEST_FILE feature.
Success.Dir="/sci/users/jbrown1/success"
[Log.Info]
#Log.MaxSize="1048576"
Log.MaxSize="35000"

Sterling Connect:Direct for UNIX: User Guide

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

Chapter 3. Sterling Connect:Direct Utilities

Sterling Connect:Direct for UNIX: User Guide

Chapter 4. Writing Custom Programs

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

Compiling Custom Programs

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

C++ Compiler

AIX

IBM XL C++ V8.0 for AIX

Sun Solaris

SPARC/x86 C++5.7

aCC: HP ANSI C++ B3910B A.03.73

HP-Itanium

aCC: HP ANSI C++ B3910B A.06.07

Linux

c++ version 3.3.3

Use the commands defined in the following table to compile a custom C++
program using the C++ API calls:
Platform C++ Compile Command
AIX
64-bit

/usr/vacpp/bin/xlC -q64 -qinline -I../include -+ -o sdksample sdksample.C ../lib/ndmapi64.a -lbsd -ldl

-lsrc -lpthreads

32-bit

/usr/vacpp/bin/xlC -qinline -I../include -+ -o sdksample sdksample.C ../lib/ndmapi.a -lbsd -ldl -lsrc

-lpthreads

Sun
32-bit

/opt/SUNWspro/bin/CC -DBSD_COMP -I../include -o sdksample sdksample.C ../lib/ndmapi.a

-L/usr/ucblib -L/usr/lib -lsocket -lrpcsoc -lnsl -lelf -ldl
Note: If /usr/ucblib is not in the LD_LIBRARY_PATH variable, add -R/usr/ucblib to the compile
command.

Copyright IBM Corp. 1999, 2014

Platform C++ Compile Command

64-bit

/opt/SUNWspro/bin/CC -xarch=generic64 -DBSD_COMP -I../include -o sdksample sdksample.C

../lib/ndmapi64.a
-L/usr/ucblib/sparcv9 -L/usr/lib/sparcv9
-L/usr/ucblib/amd64 -lsocket -lrpcsoc -lnsl -lelf -ldl
-R/usr/ucblib/sparcv9 -R/usr/ucblib/amd64

HP
32-bit

/opt/aCC/bin/aCC -AA -I../include -o sdksample sdksample.C ../lib/ndmapi.a -lrpcsoc -lnsl -ldld

-Wl,+s

64-bit

/opt/aCC/bin/aCC -AA +DD64 -I../include -o sdksample sdksample.C ../lib/ndmapi64.a

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

HP-Itanium
32-bit

/opt/aCC/bin/aCC -I../include -o sdksample sdksample.C ../lib/ndmapi.a -lrpcsoc -lnsl -ldld -Wl,+s

-lunwind

64-bit

/opt/aCC/bin/aCC +DD64 -I../include -o sdksample sdksample.C ../lib/ndmapi64.a -L/usr/lib/hpux64

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

Linux
32-bit

g++ -m32 -I../include -O -DLINUX -o sdksample sdksample.C ../lib/ndmapi.a -ldl -lnss_nis

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

64-bit

g++ -I../include -O -DLINUX -o sdksample sdksample.C ../lib/ndmapi64.a -ldl -lnss_nis

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

To build a C++ program using the C API calls, such as the apicheck.C sample
program, replace the sdksample.C parameter with the name of the C++ program
and rename the output file parameter, -o sdksample, to the name of the output file
you want to create such as apicheck.
Use the commands defined in the following table to compile a C program:
Platform C Compile Command
AIX
32-bit

/usr/vacpp/bin/xlc -I../include -+ -o apicheck apicheck.c ../lib/ndmapi.a -lbsd -ldl -lsrc -lC -lpthreads

64-bit

/usr/vacpp/bin/xlc -q64 -I../include -+ -o apicheck apicheck.c ../lib/ndmapi64.a -lbsd -ldl -lsrc -lC
-lpthreads

Sun
32-bit

/opt/SUNWspro/bin/cc -DBSD_COMP -I../include -o apicheck apicheck.c ../lib/ndmapi.a -L/usr/ucblib

-L/usr/lib -lCstd -lsocket -lrpcsoc -lnsl -lelf -ldl -lCrun
Note: If /usr/ucblib is not in the LD_LIBRARY_PATH variable, add -R/usr/ucblib to the compile
command.

64-bit

/opt/SUNWspro/bin/cc -xarch=generic64 -DBSD_COMP -I../include -o apicheck apicheck.c

../lib/ndmapi64.a
-L/usr/ucblib/sparcv9 -L/usr/lib/sparcv9
-L/usr/ucblib/amd64 -lsocket -lCstd -lCrun -lrpcsoc -lnsl -lelf -ldl
-lCrun -R/usr/ucblib/sparcv9 -R/usr/ucblib/amd64

Sterling Connect:Direct for UNIX: User Guide

Platform C Compile Command

HP
32-bit

/opt/ansic/bin/cc -I../include -o apicheck apicheck.c ../lib/ndmapi.a -lrpcsoc -lnsl -ldld -Wl,+s -lcl
-lstd_v2 -lCsup_v2

64-bit

/opt/ansic/bin/cc +DD64 -I../include -o apicheck apicheck.c ../lib/ndmapi64.a -L/usr/lib/pa20_64 -lnsl

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

HP-Itanium
32-bit

/opt/ansic/bin/cc -I../include -o apicheck apicheck.c ../lib/ndmapi.a -lrpcsoc -lnsl -ldld -Wl,+s -lcl
-lstd_v2 -lCsup -lunwind

64-bit

/opt/ansic/bin/cc +DD64 -I../include -o apicheck apicheck.c ../lib/ndmapi64.a -L/usr/lib/hpux64

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

Linux
32-bit

gcc -m32 -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi.a -ldl -lnss_nis

/usr/lib/libstdc++.so.5

64-bit

gcc -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi64.a -ldl -lnss_nis /usr/lib64/

libstdc++.so.5
Note: A 64-bit Linux OS installation is required to compile 64-bit binaries.

LinuxS390
32-bit

gcc -m31 -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi.a -ldl -lnss_nis

/usr/lib/libstdc++.so.5

64-bit

gcc -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi64.a -ldl -lnss_nis /usr/lib64/

libstdc++.so.5
Note: A 64-bit Linux OS installation is required to compile 64-bit binaries.

Writing Custom C Programs

If you write a custom program using the C API calls, you must include the header
file ndmapi.h and link it with ndmapi.a. A sample program called apicheck.c is
provided.
For Java programming, you can call the C API functions by using the JNI and the
libndmapi shared objects: libndmapi.sl for HP and libndmapi.so for the other
supported platforms. Although the JNI is supported, the Sterling Connect:Direct
Java Application Interface is recommended for Java programs that invoke the
services of Sterling Connect:Direct.
Note: The environment variable NDMAPICFG must be set to the pathname of the
client configuration file. Refer to Overview of the Command Line Interface on
page 1 for instructions on setting the environment variable.
Use the following Sterling Connect:Direct API functions for C and C++ programs:
C++ Function

C Function

Description

ndmapi_connect()

ndmapi_connect_c()

Establishes a connection with the server.

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

Chapter 4. Writing Custom Programs

C++ Function

C Function

Description

ndmapi_sendcmd()

ndmapi_sendcmd_c()

Sends commands to Sterling Connect:Direct.

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

ndmapi_recvresp()

ndmapi_recvresp_c()

Receives responses to commands sent to

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

ndmapi_disconnect() ndmapi_disconnect_c() Terminates the API connection.

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

functions.
v Informational responses return information about the submitted command.
v Data responses, stored in the resp_buffer, contain data records.
v Error responses return ERROR_H, a pointer to a linked list of all errors found.
The ID field values are fixed for use when debugging. The msgid, feedback, and
rc fields are specified by Sterling Connect:Direct and are referred to in message
text. The subst field points to a string that contains substitution variable
information to be inserted appropriately in the message text. The error control
structure keeps track of the current and total number of errors. You can move
through the errors by using the next pointer in error entry blocks.
The following code defines the ERROR_H structure:
#define NDM_ERR_ENT_T struct NDM_ERR_ENT_S
#define NDM_ERR_ENT_H NDM_ERR_ENT_T *
#define NDM_ERR_CTL_T struct NDM_ERR_CTL_S
#define ERROR_H
NDM_ERR_CTL_T *
struct NDM_ERR_ENT_S
{
int32
id;
char
msgid[MSGIDLEN];
int32
feedback;
int32
rc;
char
*subst;
NDM_ERR_ENT_H
next;
};
struct NDM_ERR_CTL_S
{
int32
id;
int32
cur_entry;
int32
num_entries;
NDM_ERR_ENT_H
next;
};

Creating a Connection to Sterling Connect:Direct Using

ndmapi_connect() or ndmapi_connect_c()
Use ndmapi_connect() or ndmapi_connect_c() to create a connection to Sterling
Connect:Direct so that an application can send commands and receive responses

Sterling Connect:Direct for UNIX: User Guide

from the commands. Control returns to the application when the connection is
established and Sterling Connect:Direct is ready for the first API request or when
an error condition is set.
Following is the format for the ndmapi_connect() or ndmapi_connect_c() function:
int32 ndmapi_connect ERROR_H error, char *

ndm_hostname, char *

ndm_portname

The following table describes the parameters for the ndmapi_connect() or

ndmapi_connect_c() function:
Parameter

Description

Value

error

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

that contains error information or status information.

ndm_hostname

NullA pointer to the text specification of the Sterling

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

ndm_portname

A pointer to the host port number. If this parameter is Pointer

not specified, the environment variable TCPPORT is
checked. If no value is specified, the value of the
tcp.port in the CLI/API configuration file is checked. If
no value is specified, the default value 1363 is used.

The ndmapi_connect() or ndmapi_connect_c() function has the following return

codes:
Parameter

Description

NDM_NO_ERROR

A session was established with the server.

NDM_ERROR

A session was not established with the

server. Consult the error structure for
detailed error status.

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

to the sun1 host:
rc=ndmapi_connect (error, "sun1", "3122");

Terminating a Connection Using ndmapi_disconnect() or

ndmapi_disconnect_c()
Use ndmapi_disconnect() or ndmapi_disconnect_c() to terminate a connection to
Sterling Connect:Direct that was established by a call to ndmapi_connect() or
ndmapi_connect_c(). The ndmapi_disconnect() or ndmapi_disconnect_c()function
call is the following:
void ndmapi_disconnect

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

ndmapi_disconnect_c(). Following is a sample ndmapi_disconnect() function:
ndmapi_disconnect ();

Chapter 4. Writing Custom Programs

Receiving Responses Using ndmapi_recvresp() or

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

error int32 *

resp_length, char *

resp_buffer,

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

Parameter

Description

Value

error

A pointer to a Sterling
Connect:Direct-defined structure that
contains error information or status
information.

Pointer

resp_length

A pointer to the length, in bytes, of the

application buffer to receive the
response. The API sets this parameter to
the number of bytes returned.

Pointer to number of bytes

returned or 0 if you no longer
want to receive responses.
Setting this field to zero purges
all queued responses.

resp_buffer

A pointer to the application buffer that

receives the command or submit
response. This buffer should allocate
4096 bytes.

A local buffer, with a size greater

than or equal to that set by
resp_length and filled in by
ndmapi_recvresp() or
ndmapi_recvresp_c().

The format of resp_buffer is a free-form

The CLI passes the resp_buffer to
text record structure. Field names are
AWK for parsing. Valid values
four characters long and all uppercase.
include:
The data can be any length and can
include blanks. The structure is:
ADMNSterling Connect:Direct
administrator name
field name=data | field name=data |...
For example:
SUBM = username | PNUM = 12 |
PNAM = proc1 |...

ADPHSterling Connect:Direct
administrator phone number
CCODCompletion code
CKPTCheckpoint
CLASClass
CSDSCopy step start
timestamp
CSPESecure+ enabled indicator
CSPPSecure+ protocol
CSPSSecure+ cipher suite

Sterling Connect:Direct for UNIX: User Guide

Parameter

Description

Value
DBLWDestination file blocks
received
DBYWBytes written
DBYXBytes received
DCODDestination completion
code
DDAYSubmit date
DDS1Destination disposition 1
DDS2Destination disposition 2
DDS3Destination disposition 3
DESCSterling Connect:Direct
administrator description
DFILDestination file
DLDRDownload directory
restriction
DMSGDestination message ID
DNVLDestination number of
volumes
DRCWRecords written
DRUXRUs received
DVCNDestination file volume
count
DVOLDestination volume
array
DVSQDestination file volume
sequence number
ECMPExtended compression
ON or OFF
ECPRExtended compression
percentage
ECTPExtended compression
type
ETMCEla[sed clock time
ETMKElapsed kernal time
ETMUElapsed user time
FROMCopy sending node

Chapter 4. Writing Custom Programs

Parameter

Description

Value
ICRCCRC indicator
LCCDLocal completion code
LCLPLocal IP address and port
number
LKFLLink fail
LMSGLocal message ID
LNODLocal node
MSGIMessage ID
MSGTMessage text
MSSTShort text
OCCDOther completion code
OERROther node in error
OMSGOther message ID
PACCPNODE account
PCRCCRC indicator
PFILProcess file
PNAMProcess name
PNODPNODE
PNUMProcess number
PPMNPDS member name
PRTYPriority
QUEUQueue
RECCRecord category
RECIRecord ID
RETARetain Process
RMTPRemote IP address and
port number
RSTRProcess restarted
RUSZRU Size
SACCSNODE account
SBIDSubmitter node ID
SBLRSource file blocks sent

Sterling Connect:Direct for UNIX: User Guide

Parameter

Description

Value
SBNDSubmitter node name
SBYRBytes read
SBYXBytes sent
SCMPStandard compression
SCODSource completion code
SCPRStandard compression
percentage
SDDYSchedule date
SDS1Source disposition 1
SDS2Source disposition 1
SDS2Source disposition 2
SDS3Source disposition 3
SELAElapsed time of the event
SFILSource file
SFSZsource file size
SMSGSource message ID
SNAMStep name
SNODSNODE
SNVLSource number of
volumes
SOPTSYSOPTS record
SRCRRecords read
SRUXRUs sent
SSTAStart time of the event
STARStart log date/time for
record
STATProcess status
STDLCopy termination record
(CTRC) log time
STIMSchedule time
STOPStop time of the event
STPTStop time of the event
(STOP duplicate)
STRTStart time of the event
(SSTA duplicate)
Chapter 4. Writing Custom Programs

Parameter

Description

Value
SUBMSubmitter ID
SUBNSubmitter node
SUMMSummary output
selector
SVCNSource file volume count
SVOLSource volume array
SVSQSource file volume
sequence number
TIMESubmit time
TZDILocal time zone delta
from GMT
XLATTranslation
ZLVLZlib compress level
Zlibmemory level
Zlibwindow size

resp_moreflag Indicates that more ndmapi_recvresp()

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

None

The ndmapi_recvresp() or ndmapi_recvresp_c() function has the folliowing return

codes:
Return Code

Description

NDM_NO_ERROR

The function completed successfully.

NDM_ERROR

An error occurred. Consult the error

structure for detailed error status.

TRUNCATED

Data is truncated because the receiving

buffer is too small.

Following is a sample ndmapi_recvresp() function:

int32 rc, resp_length;
int32 resp_moreflag;
char resp_buffer[makbuf];
rc= ndmapi_recvresp (error,
&resp_length,
resp_buffer,
&resp_moreflag
);

Sterling Connect:Direct for UNIX: User Guide

Sending a Command to Sterling Connect:Direct Using

ndmapi_sendcmd() or ndmapi_sendcmd_c()
Use ndmapi_sendcmd() or ndmapi_sendcmd_c() to allow a command to be sent to
a Sterling Connect:Direct application. Following is the format of
ndmapi_sendcmd() or ndmapi_sendcmd_c():
int32 rc, resp_moreflag;
struct sendcmd_data ret_data;
rc=ndmapi_sendcmd (error,
"select process pnumber=2,",
&resp_moreflag,
&ret_data
);

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

Parameter

Description

Value

error

A pointer to a Sterling Connect:Direct-defined structure

that contains error information or status information.

Pointer

cmd_text

A pointer to the null-terminated text string that specifies

the command to send to Sterling Connect:Direct. The
command text must be followed by a semicolon and
terminated with a null.

Pointer to a text
string

When you use the submit=filename command from the

API, ensure that you allocate enough storage for the
Process text. The text of the Process submitted is
returned in the text string associated with this parameter
when the function completes. If you do not allocate
enough storage for the Process text, a core dump can
result.
resp_moreflag A pointer to the flag that indicates that more responses
are pending for the command just executed. Invoke
ndmapi_recvresp() or ndmapi_recvresp_c() to retrieve
the extra responses.

Pointer to a flag

ret_data

Pointer to a
structure

A pointer to a structure containing internal response

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

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

A pointer to a string with the name of the command

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

Pointer to name
of command

Chapter 4. Writing Custom Programs

Parameter

Description

Value

cmd_id

A four-byte identifier of the command that was found in

the command text. Following are the four-byte
identifiers:

Four-byte
identifier

/**************Command IDs*******************/
#define CHANGE_PROCESS 0x43484750 /* "CHGP" */
#define DELETE_PROCESS 0x44454c50 /* "DELP"*/
#define FLUSH_PROCESS 0x464c5350 /* "FLSP" */
#define SELECT_PROCESS 0x53454c50 /* "SELP"*/
#define SELECT_STATISTICS 0x53454c53 /* "SELS" */
#define SUBMIT 0x5355424d /* "SUBM" */
#define TRACE_API 0x41504920 /* "API " */
#define TRACE_CMGR 0x434d4752 /* "CMGR" */
#define TRACE_SMGR 0x534d4752 /* "SMGR" */
#define TRACE_PMGR 0x504d4752 /* "PMGR" */
#define TRACE_COM 0x434f4d4d /* "COMM"*/
#define TRACE 0x54524143 /* "TRAC" */
#define STOPNDM 0x53544F50
/* "STOP" */
The CLI uses these identifiers to ensure that rules are
being followed. For instance, if an ndmapi_sendcmd
returns with the resp_moreflag set and the cmd_id is not
SELECT_STATISTICS or SELECT_PROCESS, the CLI
generates an error.
data1, data2,
and data3

For future expansion. data1 is used with the submit

command to return the Process number. data2 is used
with the submit command to return the result of the
Process (0, 4, 8, or 16)

The ndmapi_sendcmd_c() function call has the following return codes:

Return Code

Description

NDM_NO_ERROR or Process Number

The function completed successfully.

NDM_ERROR

An error occurred. Consult the error

structure for detailed error status.

Following is a sample ndmapi_sendcmd() function:

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

Writing Custom C++ Programs

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

Sterling Connect:Direct for UNIX: User Guide

Note: The environment variable NDMAPICFG must be set to the pathname of the
client configuration file. Refer to Starting the CLI on page 1for instructions on
setting the environment variable.
To use the ConnectDirectSession class, your application must include the
cdunxsdk.h header file provided in the installation and must link with the
ndmapi.a file. Following is a sample ConnectDirectSession class program:
#include "cdunxsdk.h"
#include <iostream.h>
#include <string.h>
void getError(ConnectDirectSession& cdSess);
main()
{
ConnectDirectSession cdSess;
char processText[16384];
if (cdSess.SessionINF->Connect() == CD_SUCCESS)
{
strcpy(processText,"submit maxdelay=unlimited sdksample process snode=SNODENAME ");
strcat(processText,"copy00 copy from (file=sample.txt pnode)");
strcat(processText,"
to (file=sample.000 snode disp=rpl) ;");
if (cdSess.SessionINF->SendCommand(processText) == CD_SUCCESS)
{
printf("%s completed, pnumber = %ld.\n",
cdSess.SessionINF->GetCommandName(),
cdSess.SessionINF->GetProcessNumber());
sprintf(processText, "SELECT STATISTICS PNUMBER=%ld DETAIL=YES ;", cdSess.SessionINF>GetProcessNumber());
(cdSess.SessionINF->SendCommand(processText) == CD_SUCCESS)
{
}
else
{
getError(cdSess);
}
}
else
{
getError(cdSess);
}
cdSess.SessionINF->DisConnect();
}
else
{
getError(cdSess);
}
}
void getError(ConnectDirectSession& cdSess)
{
if (cdSess.SessionINF->GetFirstError())
{
printf("\nError Message: %s",
cdSess.SessionINF->GetMsgID());
printf("\nError Feedback: %d",
cdSess.SessionINF->GetFeedBackCode());
printf("\nError RC:
%d",
cdSess.SessionINF->GetReturnCode());
printf("\nError SUBST:
%s\n", cdSess.SessionINF->GetSubstitute());
}
while(cdSess.SessionINF->GetNextError())
{
printf("\nError Message: %s",
cdSess.SessionINF->GetMsgID());
printf("\nError Feedback: %d",
cdSess.SessionINF->GetFeedBackCode());
printf("\nError RC:
%d",
cdSess.SessionINF->GetReturnCode());
printf("\nError SUBST:
%s\n", cdSess.SessionINF->GetSubstitute());
}
}

The ConnectDirectSession class methods are described in the following table:

Chapter 4. Writing Custom Programs

Method

Description

Parameter

Return Values

Connect

Provides a connection to the

Sterling Connect:Direct server.

DisConnect

Disconnects the current session.

void

CD_SUCCESS or
CD_FAILURE

SendCommand

Sends a Sterling Connect:Direct

command to the server for
processing.

Pointer to a
command
text buffer.

CD_SUCCESS or
CD_FAILURE

ReceiveResponse

Receives the response from a

previously issued command,
such as the select statistics
command.

void

CD_SUCCESS or
CD_FAILURE

GetResponse

Retrieves the response from the

ReceiveResponse call.

void

Pointer to a
response buffer.

GetResponseLength Returns the length of the

previously received response
buffer.

void

Length of the
response buffer from
the previously
issued call.

MoreData

void

TRUEIf more data

is outstanding.

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

Returns a value indicating if

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

FALSEIf no data
is outstanding.

GetCommandName Returns the command name of

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

void

Pointer to a
command name
buffer.

GetProcessNumber Returns the Process number of a

previously issued submit
command.

void

Process number of a
submit command.

GetProcessCount

-1If no submit
command can be
found.

Returns the number of Processes void

affected by the last send
command that issued a delete,
change, or flush process.

Process number of a
submit command
that issued a delete,
change or flush
process.
-1If no submit
command can be
found.

GetCurrentError

Moves the error data pointer to

the current error in the list.

void

TRUEIf successful
FALSEIf no
current error exists.

GetNextError

Moves the error data pointer to

the next error in the list.

void

TRUEIf successful

Sterling Connect:Direct for UNIX: User Guide

FALSEIf no more
errors are found.

Method

Description

Parameter

Return Values

GetPreviousError

Moves the error data pointer to

the previous error in the list.

void

TRUEIf successful

Moves the error data pointer to

the first error in the list.

void

GetLastError

Moves the error data pointer to

the last error in the list.

void

TRUEIf successful,
otherwise FALSE.

GetMsgID

Retrieves the message of the

current error data block.

void

Return Value:
Pointer to a message
ID if data block is
value.

GetFirstError

FALSEIf no
previous error
exists.
TRUEIf successful
FALSEIf no error
is found.

You must call one of the

GetXXXXError methods before
calling this method in order to
retrieve the proper results.
GetFeedBackCode

Returns the feedback code of the void

current error data block.

Feedback code.

GetReturnCode

Returns the Sterling

Connect:Direct return code.

void

One of the valid

Sterling
Connect:Direct
return code: 1,4,8,16.

GetStatus

Returns the status.

void

Sterling
Connect:Direct
status code.

GetSubstitute

Returns the current substitution

buffer associated with the error.

void

Pointer to a
substitution buffer.

DisplayError

Displays the current error chain

to an output location.

Parameters:
Pointer to a
file I/O
structure.

Return Value:
Returns the highest
error found in the
error chain or -1 on
error.

Following is the ConnectDirectSession class header:

#include <stdio.h>
// Error enumeration.
typedef enum CDErrorCode
{
CD_SUCCESS = 0,
CD_FAILURE = -1
} CDErrorCode;
// <<Interface>>
class CDSession
{
public:
// Communication methods...
virtual CDErrorCode Connect(void) = 0;
virtual CDErrorCode Connect(char *IpAddress, char *IpPort) = 0;
virtual CDErrorCode DisConnect(void) = 0;
virtual CDErrorCode SendCommand(char *CmdText) = 0;
virtual CDErrorCode ReceiveResponse(void) = 0;
Chapter 4. Writing Custom Programs

// Methods for retrieving ReceiveResponse data...

virtual const char *GetResponse(void) = 0;
virtual int
GetResponseLength(void) = 0;
virtual bool
MoreData(void) = 0;
// Methods for retrieving SendCommand return data...
virtual const char *GetCommandName(void) = 0;
virtual long
GetProcessNumber(void) = 0;
virtual long
GetProcessCount(void) = 0;
// Methods to iterate over error collection ...
virtual bool
GetCurrentError(void) = 0;
virtual bool
GetNextError(void) = 0;
virtual bool
GetPreviousError(void) = 0;
virtual bool
GetFirstError(void) = 0;
virtual bool
GetLastError(void) = 0;
// Methods to retrieve error data...
virtual const char *GetMsgID(void) = 0;
virtual int
GetFeedBackCode(void) = 0;
virtual int
GetReturnCode(void) = 0;
virtual int
GetStatus(void) = 0;
virtual const char *GetSubstitute(void) = 0;
// Method to display error collection...
virtual int
DisplayError(FILE *Output) = 0;
};
class ConnectDirectSession
{
public:
// Interface classes
CDSession *SessionINF;
ConnectDirectSession();
~ConnectDirectSession();
};

Sterling Connect:Direct for UNIX: User Guide

Chapter 5. Writing User Exits

User Exit Programs
The user exit API functions allow you to write custom programs to use with
Sterling Connect:Direct. The user exit programs are used by Sterling Connect:Direct
to invoke user-specific logic at strategic points within Sterling Connect:Direct
execution. User exit programs must be C or C++ language programs and cannot be
shell scripts. The PMGR invokes the Statistics user exit program when you start
Sterling Connect:Direct and the exit runs as long as Sterling Connect:Direct runs.
The SMGR invokes the File Open and Security user exits for each session and
stops them when the particular session terminates.
Note: exit_skeleton.c and exit_skeleton.C contain working examples of all three
exits and can be made with the make_exit_c and make_exit_C make files.
The user exit programs are described in the following:
Program

Description

File Open Exit

Sterling Connect:Direct sends a message to

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

Security Exit

The Security Exit enables you to implement

your own security system or provide access
to a third-party security system.

Statistics Exit

The Security Exit enables you to implement

your own security system or provide access
to a third-party security system.

User Exit Functions

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

C++ Function

C Function

Description

exit_child_init()

exit_child_init_c()

Use this function as the first line in a user exit

program to initialize communications between
Sterling Connect:Direct and the user exit program.

recv_exit_msg()

recv_exit_msg_c()

Used by both Sterling Connect:Direct and the user

exit program to receive a message from the other
Process. The receive exit messages wait for a
response from the other Process.

send_exit_file()

send_exit_file_c()

The user exit program uses this function when it

has opened a file for Sterling Connect:Direct. This
function uses underlying UNIX methods to pass
an open file descriptor. from one Process to
another.

send_exit_msg()

send_exit_msg_c()

Both Sterling Connect:Direct and the user exit

program use this function to send a message to
the other Process. Send messages are followed
with a receive message to get the response from
the other Process.

Initializing Communications with exit_child_init() or

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

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

Parameter

Description

Value

logfile

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

The exit_child_init() or exit_child_init_c() function have the following return

codes. Return codes for the function are defined in ndmapi.h.

Return Code

Description

GOOD_RC

Communications between Sterling

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

ERROR_RC

Communications between Sterling

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

Sterling Connect:Direct for UNIX: User Guide

Waiting for a Message Using recv_exit_msg() or

recv_exit_msg_c()
The recv_exit_msg() or recv_exit_msg_c() function waits until it receives a message
from Sterling Connect:Direct. Control is suspended until a message is received or
an error occurs. The recv_exit_msg() has the following format:
int recv_exit_msg( int exit_flag )
int * msg_type,
char * recv_buf,
int * recv_buf_len

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

Parameter

Description

Value

exit_flag

A flag to specify the recipient ID. The only valid

value a user exit program can use is
EXIT_PROGRAM.

EXIT_PROGRAM

msg_type

A pointer to the name of the received message.

Messages are requests from Sterling Connect:Direct
and the associated response from the user exit
program.

Pointer to message

recv_buf

A pointer to the memory location of the message.

Pointer to message

recv_buf_len

The length in bytes of the message to be received.

Length of message

The recv_exit_msg()or recv_exit_msg_c() functions have the following return codes.

Return codes for the function are defined in ndmapi.h.
Return Code

Description

GOOD_RC

The message was received successfully.

ERROR_RC

An error occurred and the message was not

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

Passing a File Descriptor Using send_exit_file() or

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

exit_flag

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

Parameter

Description

Value

exit_flag

A flag to specify the sender ID. The only valid value a

user exit program can use is EXIT_PROGRAM.

EXIT_PROGRAM

The file descriptor of a file that the user exit program

File descriptor
opened in the place of Sterling Connect:Direct, similar to
one returned by the open(2) function.

Chapter 5. Writing User Exits

The send_exit_file() or send_exit_file_c() function calls have the following return

codes. Return codes for the function are defined in ndmapi.h.
Header

Header

GOOD_RC

The file descriptor was received successfully.

ERROR_RC

An error occurred and the file descriptor

was not sent successfully. Possible causes
include: Sterling Connect:Direct terminated,
an invalid value used for the exit_flag or fd
parameters, or the last message sent was not
send_exit_msg.

Sending a Message to Sterling Connect:Direct Using

send_exit_msg() or send_exit_msg_c()
The send_exit_msg() or send_exit_msgc() function enables the user exit program to
send a message to Sterling Connect:Direct. This function returns control to the
caller immediately after the message is queued.
Following is the format of the send_exit_msg() function:
int send_exit_msg int exit_flag
int msg_type,
char * send_buf,
int send_buf_len

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

Parameter

Description

Value

exit_flag

A flag to specify the sender ID. The only valid

value a user exit program can use is
EXIT_PROGRAM.

EXIT_PROGRAM

msg_type

A message name. Messages are requests from

Pointer to message
Sterling Connect:Direct and the associated response
from the user exit program.

send_buf

A pointer to the memory location of the message to Pointer to message

be sent.

send_buf_len

The length in bytes of the message to be sent.

Length of message

Following are the return codes for send_exit_msg() or send_exit_msg_c(). Return

codes for the function are defined in ndmapi.h.

Return Code

Description

GOOD_RC

The message was sent successfully.

ERROR_RC

An error occurred and the message was not

sent successfully. Possible causes include:
Sterling Connect:Direct terminated or an
invalid value is used for the exit_flag or
msg_type parameters.

Sterling Connect:Direct for UNIX: User Guide

Overview of User Exit Messages

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

Statistics Exit Message

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

File Open Exit Messages

The file open exit has four types of messages:
v FILE_OPEN_OUTPUT_MSG
v FILE_OPEN_OUTPUT_REPLY_MSG
v FILE_OPEN_INPUT_MSG
v FILE_OPEN_INPUT_REPLY_MSG
The file open exit has the following limitations:
v The oflag parameter passed to the user exit is already calculated based on the
file disposition, as explicitly specified on the copy statement or using the default
value. If the user exit changes the oflag to truncate and the original disposition
is mod meaning the copy will append to the end of file if the file already exists,
then the user exit causes the Process to behave differently from how the Process
language is documented.
v Do not change the file type specified by the Process. For example, if the Process
specifies a regular file, the user exit cannot open and return a file descriptor for
a pipe. No facility is available to modify contents of the copy control block and
return it to Sterling Connect:Direct.
v If the oflag specifies opening a file with write access and the user exit changes
access to read-only, Sterling Connect:Direct will fail when it attempts to write to
a read-only file.
v The upload and download parameters that restrict directory access are ignored
for this user exit.

FILE_OPEN_OUTPUT_MSG
During the copy statement process, Sterling Connect:Direct sends a
FILE_OPEN_OUTPUT_MSG to the user exit program to open the destination file.
The FILE_OPEN_OUTPUT_MSG contains:
v The open function oflag parameter (for example,
O_CREAT|O_RDWR|O_TRUNC)
v The open function mode parameter, which controls file permissions
v UNIX user ID that will own the file
v UNIX group ID that will own the file
Chapter 5. Writing User Exits

v UNIX user name

v A copy of the Sterling Connect:Direct copy control block
v A copy of the Sterling Connect:Direct parsed sysopts structure (the copy control
block contains the actual raw version from the process)

FILE_OPEN_OUTPUT_REPLY_MSG
The user exit program sends a reply message to the Sterling Connect:Direct
FILE_OPEN_OUTPUT_MSG. The FILE_OPEN_OUTPUT_REPLY_MSG contains:
v Status value of zero for successful or non zero for failure
v Status text message (if status value is failure, status text message is included in
the error message)
v Pipe pid (for pipe I/O, the UNIX process ID of the shell process that is
performing the shell command for pipe I/O)
v Actual file name opened (to be used in statistics log messages)
If the status value is zero for successful, the user exit program must immediately
call send_exit_file() or send_exit_file_c() to send the file descriptor of the opened
file to Sterling Connect:Direct.

FILE_OPEN_INPUT_MSG
During the copy statement Process, Sterling Connect:Direct sends a
FILE_OPEN_INPUT_MSG to the user exit program to open the source file. The
FILE_OPEN_INPUT_MSG contains:
v The open function oflag parameter (for example, O_RDONLY)
v The open function mode parameter, which controls file permissions
v
v
v
v
v

UNIX user ID that will own the file

UNIX group ID that will own the file
UNIX user name
A copy of the Sterling Connect:Direct copy control block
A copy of the Sterling Connect:Direct parsed sysopts structure (the copy control
block contains the actual raw version from the Process)

FILE_OPEN_INPUT_REPLY_MSG
This message type is used when the user exit program sends a reply message to
the Sterling Connect:Direct FILE_OPEN_INPUT_MSG. The
FILE_OPEN_INPUT_REPLY_MSG contains:
v Status value of zero for success or non zero for failure
v Status text message (if status value is failure, status text message is included in
the error message)
v Pipe pid (for pipe I/O, the UNIX process ID of the shell process that is
performing the shell command for pipe I/O)
v Actual file name opened (used in statistics log messages)

Security Exit Messages

The security exit contains four types of messages:
v GENERATE_MSG
v GENERATE_REPLY_MSG

Sterling Connect:Direct for UNIX: User Guide

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

GENERATE_MSG
Sterling Connect:Direct sends a generate message to the user exit program at the
start of a session to establish a security environment. The PNODE sends the
GENERATE_MSG to the security exit to determine a user ID and security token to
use for authentication on the SNODE. The GENERATE_MSG contains:
v Submitter ID
v PNODE ID
v PNODE ID password, if user specified one
v SNODE ID
v SNODE ID password, if user specified one
v PNODE name
v SNODE name

GENERATE_REPLY_MSG
The user exit program sends a reply message to Sterling Connect:Direct. The
GENERATE_REPLY_MSG contains:
v Status value of zero for success or non zero for failure
v Status text message (if status value is failure, status text message is included in
the error message)
v ID to use for security context on the SNODE side (may or may not be the same
ID as in the generate message)
v Security token used in conjunction with ID for security context on the SNODE
side

VALIDATE_MSG
Sterling Connect:Direct sends a validate message to the user exit program. The
SNODE sends the VALIDATE_MSG to the security exit to validate the user ID and
security token received from the PNODE. The VALIDATE_MSG contains:
v Submitter ID
v PNODE ID
v PNODE ID password, if user specified one
v SNODE ID
v SNODE ID password, if user specified one
v
v
v
v

PNODE name
SNODE name
ID to use with security token
Security token (password, PASSTICKET, or other security token)

Chapter 5. Writing User Exits

VALIDATE_REPLY_MSG
The user exit program sends a reply message to the Sterling Connect:Direct
VALIDATE_MSG. The VALIDATE_REPLY_MSG contains:
v Status value of zero for success or non zero for failure
v Status text message (if status value is failure, status text message is included in
the error message)
v ID used for security context
v Security token to use in conjunction with ID for security context

User Exit Stop Message

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

Copy Control Block

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

Exit Log Files

If user exit programs are specified in the initparm.cfg, Sterling Connect:Direct
creates exit logs. Exit log files are provided specifically for the user exit programs
and are used for debug and trace type messages. The user exit program is started
with the log file already opened on STDOUT and STDERR. The exit log files are:
v stat_exit.log
v file_exit.log
v security_exit.log
Note: You can access the log files through the normal printf() and fprintf
(stderr,...) functions.
The log files are located in the installed (d_dir) working directory:
.../d_dir/work/cd_node

Sterling Connect:Direct for UNIX: User Guide

Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte character set (DBCS) information,
contact the IBM Intellectual Property Department in your country or send
inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply
to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
Copyright IBM Corp. 1999, 2014

incorporated in new editions of the publication. IBM may make improvements

and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
J46A/G4
555 Bailey Avenue
San Jose, CA 95141-1003
U.S.A.
Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
All IBM prices shown are IBM's suggested retail prices, are current and are subject
to change without notice. Dealer prices may vary.

Sterling Connect:Direct for UNIX: User Guide

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 the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which
illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. The sample
programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.
Each copy or any portion of these sample programs or any derivative work, must
include a copyright notice as follows:
IBM 2014. Portions of this code are derived from IBM Corp. Sample Programs.
Copyright IBM Corp. 2014.
If you are viewing this information softcopy, the photographs and color
illustrations may not appear.

Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of
International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies.
A current list of IBM trademarks is available on the Web at Copyright and
trademark information at http://www.ibm.com/legal/copytrade.shtml.
Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered
trademarks or trademarks of Adobe Systems Incorporated in the United States,
and/or other countries.
IT Infrastructure Library is a registered trademark of the Central Computer and
Telecommunications Agency which is now part of the Office of Government
Commerce.
Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo,
Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or
registered trademarks of Intel Corporation or its subsidiaries in the United States
and other countries.
Linux is a registered trademark of Linus Torvalds in the United States, other
countries, or both.

Notices

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
ITIL is a registered trademark, and a registered community trademark of the Office
of Government Commerce, and is registered in the U.S. Patent and Trademark
Office.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Oracle and/or its affiliates.
Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc. in the
United States, other countries, or both and is used under license therefrom.
Linear Tape-Open, LTO, the LTO Logo, Ultrium and the Ultrium Logo are
trademarks of HP, IBM Corp. and Quantum in the U.S. and other countries.
Connect Control Center, Connect:Direct, Connect:Enterprise, Gentran,
Gentran:Basic, Gentran:Control, Gentran:Director, Gentran:Plus,
Gentran:Realtime, Gentran:Server, Gentran:Viewpoint, Sterling Commerce,
Sterling Information Broker, and Sterling Integrator are trademarks or registered
trademarks of Sterling Commerce, Inc., an IBM Company.
Other company, product, and service names may be trademarks or service marks
of others.

Sterling Connect:Direct for UNIX: User Guide

Index
Special characters
-e nn parameter, direct command 3
-h parameter, for direct 3
-n name parameter, direct command 3
-p nnnnn parameter, direct command 3
-r parameter, direct command 3
-s parameter
direct command 2
-t nn parameter, direct command 2
-x parameter, direct command 3
-z parameter, direct 3
&symbolic name parameter, submit
command 11
"Generic" Parameter Value 6
"List" Parameter Value 6

A
Accessing Sterling Connect
Direct Messages 48
API function calls 61
exit_child_init_c() function 78
exit_child_init() function 78
ndmapi_connect_c() 64
ndmapi_connect() 64
ndmapi_disconnect_c() 65
ndmapi_disconnect() 65
ndmapi_recvresp() 66
ndmapi_sendcmd() 71
ndmapi_sendcmd()_c 71
recv_exit_msg_c() 79
recv_exit_msg() 79
send_exit_file_c() 79
send_exit_file() 79
send_exit_msg_c() 80
send_exit_msg() 80

C
C program, compile command 62
C++ program, compile command 61
ccode parameter
select statistics command 26
cfgcheck utility
arguments 55
change process command
description 4
format 13
overview 13
Changing Process parameters 13
class parameter
change process command 15
submit command 7
CLI 1
CLI Commands 1
CLI history commands 4
CLI Job Control 3
cmd_id parameter 72
cmd_name parameter 71
cmd_text parameter 71
Copyright IBM Corp. 1999, 2014

cmgr parameter, trace command 35

Codepage conversion 53
comm parameter, trace command 36
Command
change process 4, 13
conventions 5
delete process 4, 15
flush process 4, 17
select process 4, 19, 22
select statistics 4, 26
stop 4, 18
trace 35
view process 4
Command abbreviations 5
Command Line Interface (CLI)
description 1
Commands
ndmmsg 49
ndmxlt 46
Compile command for a C++ program
AIX 61, 62
HP 62, 63
Linux 62, 63
LinuxS390 63
Sun 61, 62
Compiling a Translation Table 46
Compiling Custom Programs 61
Configuration Checking Utility
arguments 55
Configuration files
validate 55
Configuration Report
Sterling Connect:Direct for SWIFTNet
for UNIX 58
Configuration reports 55
Copy Control Block 84
Creating a connection using API function
calls 64
Creating a translation table 45
Creating a Translation Table 46
csdacomp Command Help 54

E
error parameter
ndmapi_connect() function 65
ndmapi_recvresp() function 66
ndmapi_sendcmd() function 71
Error responses 64
Example - Submit a Process that runs
weekly 12
Example - Submit a Process with a Start
Time 12
Example - Submit a Process with No File
Value 12
Example Submit a Process and Turn on
Tracing 13
Execution queue 41
Exit log files 84
file_exit.log 84
stat_exit.log 84
exit_flag parameter
recv_exit_msg() function 79
exit_flag parameter, send_exit_file()
function 79
exit_msg parameter
recv_exit_msg() function 80

F
File Open Exit Messages 81
FILE_OPEN_INPUT_MSG 82
FILE_OPEN_INPUT_REPLY_MSG 82
FILE_OPEN_OUTPUT_MSG 81
FILE_OPEN_OUTPUT_REPLY_MSG 82
FILE_OPEN_INPUT_MSG 82
FILE_OPEN_INPUT_REPLY_MSG 82
FILE_OPEN_OUTPUT_MSG 81
FILE_OPEN_OUTPUT_REPLY_MSG 82
filename parameter 6
flush process command 4, 17

G
D
Decompress a file on remote node during
copy step 54
Decompress a text file 53
delete process command 4, 15
destfile parameter, select statistics
command 26
detail parameter
change process command 25, 34
Detailed report for a Process 34
Determing the outcome of a Process 26
direct command
parameters, -h 3
parameters, -P 2
parameters, -r 3
parameters, -z 3
Displaying message text 49

GENERATE_MSG 83
GENERATE_REPLY_MSG 83
Generating a Configuration Report 55
base installation 56
Generating a Configuration Report on
Sterling Connect:Direct Direct for
UNIX 57

H
hold parameter
submit command
Hold queue 43

I
informational responses, API 64
Initializing communications using user
exit functions 78

L
logfile parameter
exit_child_init() function

M
Managing Processes 39
maxdelay parameter 7
Message
message ID format 48
Message file
record format 49
Message File Content 48
Message file record format 49
Message files
overview 48
Message text 49
Modifying a translation table 47
Modifying translation tables 46
Monitor Process Status in the TCQ 19
Monitoring Process status 22
Moving a CLI process
foreground 4
msg_type parameter, recv_exit_msg()
function 79
msg_type parameter, send_exit_msg()
function 80

N
ndm_hostname parameter 65
ndm_portname parameter 65
ndmapi_connect() or ndmapi_connect()_c
function
format 65
ndmapi_recvresp() function
example 70
ndmxlt command parameters
-ffiller 46
-m 46
-ooutputfile 46
-rradix 46
-ssourcefile 46
newname parameter, submit
command 7
newsnode parameter, change process
command 15

P
pacct parameter 8
Parameters, scheduling for the TCQ 39
Passing a file descriptor using user exit
functions 79
pmgr parameter, trace command 36
pname parameter
change process command 13, 17, 20,
22, 27
delete process command 16

pnodeid parameter, submit command 8

pnumber parameter
change process command 13, 17, 20,
22, 27
delete process command 16
select statistics command 27
Precompress a Binary File 53
Precompress a Text File 53
Precompress a text file with codepage
conversion 53
Precompressing/decompressing files 50
Process progression - TCQ 40
Process report
detailed 34
summary 34
prty parameter
change process command 15
submit command 8

Q
queue parameter 20, 23
change process command

20, 23

R
reccat parameter
select statistics command 27
Receiving responses using API function
calls 66
recids parameter
select statistics command 28
recv_buf_len parameter 79
release parameter 15
Remove a Process from the TCQ 15
Removing a Process from the Execution
Queue 17
resp_buffer parameter 66
resp_length parameter 66
resp_moreflag parameter
ndmapi_recvresp() function 70
ndmapi_sendcmd() function 71
Restricting Scripts and Commands 5
ret_data parameter 71
retain parameter 8

S
sacct parameter 8
Scheduling activity 39
Scheduling parameters 39
Security Exit Messages 82
GENERATE_MSG 83
GENERATE_REPLY_MSG 83
VALIDATE_MSG 83
VALIDATE_REPLY_MSG 84
select process command 4, 19, 22
select statistics command 4, 26
format 26
Send precompressed file to z/OS and
store as precompressed 54
send_buf parameter
recv_exit_msg() function 79
send_exit_msg() function 80
send_buf_len parameter 80
sendcmd_data parameter 71

Sterling Connect:Direct for UNIX: User Guide

Sending a command using function

calls 71
Sending a message using user function
exits 80
smgr parameter, trace command 37
snode parameter
change process command 14, 17, 20,
23, 32
delete process command 16
submit command 9
snodeid parameter 10
srcfile parameter
select statistics command 33
Standalone Batch Compression Utility
special considerations 50
startt parameter
select statistics command 33
submit command 11
Statistics Exit Message 81
status parameter
select process command 21, 24
Status values
overview 40
Sterling Connect:Direct command
syntax 5
Sterling Connect:Direct Commands 4
stop command 4, 18
STOP_MSG 84
Stopping Sterling Connect:Direct 18
Stopping the CLI 1
stopt parameter 33
select statistics command 33
submitter parameter
change process command 14, 18, 22,
25, 34
delete process command 16
Submitting a Process 6
Summary report for a Process 34
System diagnostics 35

T
TCQ
hold parameter 39
overview 39
Process progression 40
startt parameter 39
Terminating a connection using API
function calls 65
The Timer Queue 43
trace command 35
format 35
Translation 47
Translation table
compiling 46
creating 45, 46
modifying 47
Translation table error messages 48
Translation Tables 45

U
User
User
User
User

Exit
Exit
Exit
Exit

Functions 77
Messages 81
Programs 77
Stop Message 84

User Exit Stop Message (continued)

STOP_MSG 84
Using the Stand-alone Batch Compression
Utility 51
Using translation during file transfer
operationg 47
Utilities
translation table and the copy
statement 47

V
Validate configuration files 55
VALIDATE_MSG 83
VALIDATE_REPLY_MSG 84
view process command 4

W
Wait queue 42
Waiting for a message using user exit
functions 79
Wildcard facility 6
Writing Custom C Programs 63
Writing Custom C++ Programs 73
Writing Custom Programs 61

Index

Sterling Connect:Direct for UNIX: User Guide

Product Number: xxxx-xxx

Printed in USA

Information Theory and Coding
No ratings yet
Information Theory and Coding
27 pages
CDU UserGuide PDF
No ratings yet
CDU UserGuide PDF
98 pages
CDZ OSUser
No ratings yet
CDZ OSUser
184 pages
CD Windows System Guide
No ratings yet
CD Windows System Guide
172 pages
Dig Silent Engine
No ratings yet
Dig Silent Engine
9 pages
Merva ESA Sys Prog Guide PDF
No ratings yet
Merva ESA Sys Prog Guide PDF
202 pages
CL Programming
No ratings yet
CL Programming
586 pages
Ile RPG Programmer'S Guide: Websphere Development Studio
No ratings yet
Ile RPG Programmer'S Guide: Websphere Development Studio
606 pages
CDC Installation
No ratings yet
CDC Installation
686 pages
Rezz
No ratings yet
Rezz
342 pages
Connect:Direct Unix Administration Guide
No ratings yet
Connect:Direct Unix Administration Guide
72 pages
Rzaku
No ratings yet
Rzaku
90 pages
ILE RPG Programmer's Guide
No ratings yet
ILE RPG Programmer's Guide
504 pages
TRCuserguide
No ratings yet
TRCuserguide
142 pages
14 B2 CD 01
No ratings yet
14 B2 CD 01
602 pages
ILE RPG Programming Guide
No ratings yet
ILE RPG Programming Guide
616 pages
TSO - E Programming Guide
No ratings yet
TSO - E Programming Guide
188 pages
Connect Direct For Microsoft Windows 4.7 Documentation
No ratings yet
Connect Direct For Microsoft Windows 4.7 Documentation
324 pages
Command Line Interface
No ratings yet
Command Line Interface
740 pages
Sc092507-ILE RPG Programmers Guide 7.1
No ratings yet
Sc092507-ILE RPG Programmers Guide 7.1
616 pages
Dfsort Application Programming Guide
No ratings yet
Dfsort Application Programming Guide
896 pages
CL
No ratings yet
CL
387 pages
DFSORT Application Programming Guide
No ratings yet
DFSORT Application Programming Guide
846 pages
Debug Tool V10.1 Customization Guide
No ratings yet
Debug Tool V10.1 Customization Guide
150 pages
CPC 2
No ratings yet
CPC 2
28 pages
Frp0 BK Commands
No ratings yet
Frp0 BK Commands
540 pages
DS6000
No ratings yet
DS6000
640 pages
DFSORT
No ratings yet
DFSORT
958 pages
ACX Junos Cli
No ratings yet
ACX Junos Cli
336 pages
ISCDC For Oracle
No ratings yet
ISCDC For Oracle
104 pages
User'S Guide BACI C Compiler and Concurrent PCODE Interpreter
No ratings yet
User'S Guide BACI C Compiler and Concurrent PCODE Interpreter
13 pages
ANSI C For Programmers On UNIX Systems: Tim Love Cambridge University Engineering Department March 21, 1996
No ratings yet
ANSI C For Programmers On UNIX Systems: Tim Love Cambridge University Engineering Department March 21, 1996
73 pages
Emulator Programming Reference
No ratings yet
Emulator Programming Reference
164 pages
Primergy Serverview Suite: Irmc S2 - Integrated Remote Management Controller (Firmware Version 3.77A)
No ratings yet
Primergy Serverview Suite: Irmc S2 - Integrated Remote Management Controller (Firmware Version 3.77A)
532 pages
IMM2 00fh725 en
No ratings yet
IMM2 00fh725 en
288 pages
Awsadmst
No ratings yet
Awsadmst
371 pages
Ile RPG Programmer'S Guide: Websphere Development Studio
No ratings yet
Ile RPG Programmer'S Guide: Websphere Development Studio
558 pages
Using
No ratings yet
Using
57 pages
IBM ZOS Management Facility Configuration Guide
No ratings yet
IBM ZOS Management Facility Configuration Guide
344 pages
TWS 8.4 Reference Guide
No ratings yet
TWS 8.4 Reference Guide
627 pages
SC 415443
No ratings yet
SC 415443
301 pages
Data Stage Designer 8.5
100% (1)
Data Stage Designer 8.5
269 pages
CD Windows S DK Guide
No ratings yet
CD Windows S DK Guide
72 pages
Gnu Inetutils: Alain Magloire Et Al
No ratings yet
Gnu Inetutils: Alain Magloire Et Al
91 pages
IBM Total Storage DS6000 Command-Line Interface User's Guide
No ratings yet
IBM Total Storage DS6000 Command-Line Interface User's Guide
636 pages
Tutorial On Python Iterators and Generators
No ratings yet
Tutorial On Python Iterators and Generators
22 pages
IBM Printer and Printing
No ratings yet
IBM Printer and Printing
254 pages
C Annotations 10.9.2 version Edition Frank Brokken pdf download
100% (1)
C Annotations 10.9.2 version Edition Frank Brokken pdf download
49 pages
Itm Admin
No ratings yet
Itm Admin
324 pages
Networking TCP-IP Troubleshooting
No ratings yet
Networking TCP-IP Troubleshooting
94 pages
ESS Comand Line Interface
No ratings yet
ESS Comand Line Interface
194 pages
Course: Operating Systems Lab 1 C Programming On Linux, Mac OS X Process
No ratings yet
Course: Operating Systems Lab 1 C Programming On Linux, Mac OS X Process
25 pages
Advanced Multiplayer Game Development with Ureal Engine 5: A Comprehensive Guide to C++ Scripting
From Everand
Advanced Multiplayer Game Development with Ureal Engine 5: A Comprehensive Guide to C++ Scripting
Vladimir Kiselev
No ratings yet
CISCO PACKET TRACER LABS: Best practice of configuring or troubleshooting Network
From Everand
CISCO PACKET TRACER LABS: Best practice of configuring or troubleshooting Network
Mulayam Singh
No ratings yet
Bare Metal C: Embedded Programming for the Real World
From Everand
Bare Metal C: Embedded Programming for the Real World
Stephen Oualline
No ratings yet
C Programming for the Pc the Mac and the Arduino Microcontroller System
From Everand
C Programming for the Pc the Mac and the Arduino Microcontroller System
Peter D Minns
No ratings yet
TensorFlow Developer Certificate Exam Practice Tests 2024 Made Easy
From Everand
TensorFlow Developer Certificate Exam Practice Tests 2024 Made Easy
Mr Troy
No ratings yet
C# Package Mastery: 100 Essentials in 1 Hour - 2024 Edition
From Everand
C# Package Mastery: 100 Essentials in 1 Hour - 2024 Edition
Tenko
No ratings yet
C Programming
From Everand
C Programming
Netra
No ratings yet
Introduction to Python Programming: Do your first steps into programming with python
From Everand
Introduction to Python Programming: Do your first steps into programming with python
Greytower Corp
No ratings yet
LPIC-1 Primer
From Everand
LPIC-1 Primer
John Greene
4.5/5 (3)
Installation and Configuration of Android
No ratings yet
Installation and Configuration of Android
48 pages
Frank Wolfe
No ratings yet
Frank Wolfe
10 pages
HSC Quick Start
No ratings yet
HSC Quick Start
9 pages
Data Structures and Algorithms with JavaScript 1st Edition Michael Mcmillan download pdf
100% (12)
Data Structures and Algorithms with JavaScript 1st Edition Michael Mcmillan download pdf
60 pages
Prtgmanual Parte2
No ratings yet
Prtgmanual Parte2
930 pages
MongoDB - Course Curriculum
No ratings yet
MongoDB - Course Curriculum
5 pages
Generics
No ratings yet
Generics
84 pages
Manohar Java Developer
No ratings yet
Manohar Java Developer
5 pages
IOT Lab Manual (1) - Compressed
No ratings yet
IOT Lab Manual (1) - Compressed
50 pages
ABAP List Viewer (ALV)
No ratings yet
ABAP List Viewer (ALV)
32 pages
CS619 Final Project Viva Questions
100% (2)
CS619 Final Project Viva Questions
13 pages
Informatica Codereview Checklist
No ratings yet
Informatica Codereview Checklist
4 pages
C++ 10 Statements
No ratings yet
C++ 10 Statements
150 pages
Lab#11 Mongodb Basic CRUD Commands
No ratings yet
Lab#11 Mongodb Basic CRUD Commands
9 pages
Big-O Algorithm Complexity Cheat Sheet
No ratings yet
Big-O Algorithm Complexity Cheat Sheet
7 pages
C 2010 for Programmers 4th Edition Deitel Developer Series Paul J. Deitel - Get the ebook instantly with just one click
100% (2)
C 2010 for Programmers 4th Edition Deitel Developer Series Paul J. Deitel - Get the ebook instantly with just one click
57 pages
Workflow and Account Generator in Oracle Projects: An Oracle White Paper July 2001
No ratings yet
Workflow and Account Generator in Oracle Projects: An Oracle White Paper July 2001
27 pages
A Project Report ON College Management System: Bachelor of Computer Application
No ratings yet
A Project Report ON College Management System: Bachelor of Computer Application
29 pages
第五章：Flink Table & SQL实践原理（上）
No ratings yet
第五章：Flink Table & SQL实践原理（上）
113 pages
TCL TK Tutorial
No ratings yet
TCL TK Tutorial
176 pages
Spring Batch Reference
No ratings yet
Spring Batch Reference
287 pages
Chain of Command COC Event Handler 1656762364
No ratings yet
Chain of Command COC Event Handler 1656762364
8 pages
Software Multithreading
No ratings yet
Software Multithreading
10 pages
C Programming
No ratings yet
C Programming
35 pages
T24 Ofs
100% (6)
T24 Ofs
27 pages
PPL Unit 1 and 2 Decode Scan
No ratings yet
PPL Unit 1 and 2 Decode Scan
25 pages
UDT and UDF Related Issues
No ratings yet
UDT and UDF Related Issues
5 pages
Questions Based On Classes and Constructor: Q1. Define A Class Flight in C++ With The Following Specification
No ratings yet
Questions Based On Classes and Constructor: Q1. Define A Class Flight in C++ With The Following Specification
2 pages
A Tour Through The UNIX C Compiler
No ratings yet
A Tour Through The UNIX C Compiler
23 pages