CDZ OSUser

IBM Sterling Connect:Direct for z/OS
User Guide
Version 5.1.1
Last updated: 3 September 2014
User Guide
Version 5.1.1
Last updated: 3 September 2014
Note
Before using this information and the product it supports, read the information in Notices on page 169.
This edition applies to version 5.1.1 of IBM Connect:Direct for z/OS and to all subsequent releases and
modifications until otherwise indicated in new editions.
Copyright IBM Corporation 1999, 2012.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Chapter 1. Introduction to Sterling
Connect:Direct commands. . . . . . . 1
Supported commands . . . . . . .
Writing Sterling Connect:Direct commands
Native format . . . . . . . . .
Command example . . . . . . .
Command syntax . . . . . . . .
Indicating case sensitivity . . . . .
Indicating selection criteria . . . .
Indicating output destination . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1
2
2
3
3
6
7
7
Chapter 2. The batch interface . . . . . 9

Batch interface job requirements . . . . . .
Processing rules . . . . . . . . . .
Sample job stream to run the batch interface .
DDNAMES for DGADBATC. . . . . .
DGADBATC EXEC parameters . . . . .
DGADBATC return codes with DGADCHLA
Using the MAXDELAY keyword parameter to
synchronize submitted Processes . . . . .
.
.
.
.
.
.
. 9
. 9
. 10
. 10
. 11
. 11
. 12
Chapter 3. The Interactive User

Interface (IUI) . . . . . . . . . . . . 15
Primary Options Menu . . . . . . . . .
Navigating the Interactive User Interface . .
Using the PF Keys . . . . . . . . . .
Displaying Your User Authorization . . . .
Getting Help . . . . . . . . . . . .
Operator Tables . . . . . . . . . . . .
Messages . . . . . . . . . . . . . .
Message Example . . . . . . . . . .
Messages in a Sterling Connect:Direct/Plex
Environment . . . . . . . . . . . .
Viewing and Printing Messages Using Different
Criteria . . . . . . . . . . . . . .
Viewing a Message List . . . . . . . .
Printing Messages . . . . . . . . . .
.
.
.
.
.
.
.
.
15
17
18
18
19
19
20
21
. 22
. 22
. 23
. 24
Chapter 4. The Application Program

Interface . . . . . . . . . . . . . . 25
DGADCHLA Program. . . . . . . . .
Required Parameters for DGADCHLA . .
Extracting Return Codes . . . . . . .
UICB Fields . . . . . . . . . . .
DGADCHLA Return Codes . . . . . .
DGADCHLA Examples . . . . . . . .
Sample Job Stream for Executing the Program .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
25
26
27
29
32
32
34
Chapter 5. Managing Sessions . . . . 37

Signing On to Sterling Connect:Direct for
Timeout Problems . . . . . . .
Using SIGNON through the IUI . .
SIGNON Command . . . . . .
Signing On to the API . . . . . .
Copyright IBM Corp. 1999, 2012
z/OS
. .
. .
. .
. .
.
.
.
.
.
.
.
.
.
.
37
37
38
40
45
Signing On to Multiple Sessions . . . . .

Swap Node Command . . . . . . . . .
Using SWAP NODE through the IUI . . . .
Using SWAP NODE through the Batch Interface
Sign Off Command . . . . . . . . . . .
Using SIGNOFF Through the IUI . . . . .
Using SIGNOFF through the Batch Interface .
Sequencing the SIGNON, SWAP NODE, and
SIGNOFF Commands . . . . . . . . . .
. 46
. 48
. 48
49
. 49
. 49
. 50
. 50
Chapter 6. Building, Modifying, and

Submitting Processes . . . . . . . . 53
Process Routing . . . . . . . . . . . . .
Process Queuing. . . . . . . . . . . . .
Process Selection . . . . . . . . . . .
Intelligent Session Retry . . . . . . . . .
Process Execution Example . . . . . . . .
Process Management in a Sterling
Connect:Direct/Plex . . . . . . . . . .
SUBMIT Command. . . . . . . . . . . .
SUBMIT Command Examples . . . . . . .
Submitting Processes through the Batch Interface
Submitting Processes through the IUI. . . . . .
IUI Submit Options. . . . . . . . . . .
Validating Processes from the SB, DF, and CF IUI
Options. . . . . . . . . . . . . . .
Using the SB IUI Option to Submit a Predefined
Process . . . . . . . . . . . . . . . .
Using the DF IUI Option to Create, Edit, and
Submit Processes . . . . . . . . . . . .
Modifying and Submitting a Process Using the
DF IUI Option . . . . . . . . . . . .
Creating and Submitting a New Process Using
the DF IUI Option . . . . . . . . . . .
Submitting a Process Using the DF IUI Option .
Using Statement Models to Create a Process . .
Using the CF IUI Option to Generate a COPY
Process . . . . . . . . . . . . . . . .
Generating a COPY Process . . . . . . . .
54
54
55
55
56
60
62
70
71
71
71
72
72
74
75
75
76
76
77
78
Chapter 7. Controlling Processes in the

TCQ . . . . . . . . . . . . . . . . 83
Controlling Processes with Commands . . . .
Setting Selection Criteria . . . . . . . .
Modifying a Process in the TCQ with CHANGE
PROCESS . . . . . . . . . . . . . .
CHANGE PROCESS Command Format . . .
CHANGE PROCESS Command Examples . .
Issuing CHANGE PROCESS through the Batch
Interface . . . . . . . . . . . . .
Issuing CHANGE PROCESS through the IUI .
Suspending, Flushing, and Deleting Processes . .
SUSPEND, FLUSH, or DELETE PROCESS
Command Format . . . . . . . . . .
. 83
. 83
. 83
. 83
. 88
. 88
. 89
. 89
. 90
iii
SUSPEND, FLUSH, and DELETE Command

Examples . . . . . . . . . . . .
Issuing the SUSPEND PROCESS, DELETE
PROCESS, or FLUSH PROCESS Commands
through the Batch Interface . . . . . .
Issuing the SUSPEND PROCESS, DELETE
PROCESS, or FLUSH PROCESS Commands
through the IUI . . . . . . . . . .
Examining Processes in the TCQ . . . . .
SELECT PROCESS Command Format . .
SELECT PROCESS Command Example . .
Issuing SELECT PROCESS through the Batch
Interface . . . . . . . . . . . .
Issuing SELECT PROCESS through the IUI .
. 91
. 92
.
.
.
.
.
.
.
.
.
.
. 97
. 97
92
94
94
96
. 135
. 135
Notices . . . . . . . . . . . . . . 169
. 136
. 137
Index . . . . . . . . . . . . . . . 173
Logical Queues . . . . . . . . . . . . .
Queuing Parameters . . . . . . . . . .
TCQ Status and State Values . . . . . . .
Process Recovery . . . . . . . . . . . .
COPY Statement Checkpoint/Restart Facility
Checkpoint/Restart Examples for TCP/IP, UDT,
or LU6.2 Transfers . . . . . . . . . . .
RUN TASK Checkpoint/Restart . . . . . .
103
103
104
110
111
113
114
Chapter 9. Process Results and

Statistics . . . . . . . . . . . . . 117
Statistics Log Records. . . . . . . . . . . 117
Statistics Records Content . . . . . . . . 117
Elapsed Time Significance . . . . . . . . 118
InterConnect Option Records . . . . . . . 118
SELECT STATISTICS Command . . . . . . . 119
SELECT STATISTICS Command Format . . . 119
Using SELECT STATISTICS through the Batch
Interface . . . . . . . . . . . . . . 125
Using SELECT STATISTICS through the IUI . . 127
SELECT MESSAGE Command . . . . . . . 133
Chapter 10. The Network Map . . . . 135
iv
IBM Sterling Connect:Direct for z/OS: User Guide
Chapter 11. Utility Programs . . . . . 141

User Notification Programs. . . . . . . . .
Operator Console Notify Program (DGADTIFY)
User Notify Program (DGADTFY2) . . . . .
Dynamic Allocation Program (DGADTDYN)
Run Task Wait Program (DGADWAIT) . . . .
VSAM AMS Interface Program (DGADTAMS) . .
DGADTAMS Parameters . . . . . . . .
DGADTAMS Sample Program. . . . . . .
Symbolic Resolution Utilities (DGADTSUB and
DGADGSUB) . . . . . . . . . . . . .
Passing Variables Using DGADGSUB . . . .
Using Symbolic Variables . . . . . . . .
Sterling Connect:Direct Exits and DGADTSUB
Batch Compression Utility (DGASACMP) . . . .
DGASACMP Parameters . . . . . . . .
DGASACMP Examples . . . . . . . . .
DGASACMP Output . . . . . . . . . .
Testing the Effects of Changing Values for
Extended Compression Parameters . . . . .
Determine High-Water Mark for a Period
(DGADVITL) . . . . . . . . . . . . .
ADRDSSU Interface Program (DGADSIOX I/O
Exit) . . . . . . . . . . . . . . . .
DGADSIOX I/O Exit Sample Processes. . . .
DGADSIOX I/O exit limitations and security
considerations . . . . . . . . . . . .
Sterling Connect:Direct FTP+ for z/OS (CDFTP)
Components of Sterling Connect:Direct FTP+
Security Considerations for Sterling
Connect:Direct FTP+ . . . . . . . . . .
Configure Sterling Connect:Direct FTP+ for
z/OS . . . . . . . . . . . . . . .
Modify FTP JCL . . . . . . . . . . .
New SDGAPARM and SDGASAMP Members
Supported FTP Commands . . . . . . . .
Chapter 8. Process Queuing and

Recovery . . . . . . . . . . . . . 103
Retrieving Records from the Network Map File .

Issuing the SELECT NETMAP Command from
the IUI . . . . . . . . . . . . .
Issuing the SELECT NETMAP Command from
the Batch Interface. . . . . . . . . .
SELECT NETMAP Command Format . . .
Translating TCP/IP Host Names to Network
Addresses . . . . . . . . . . . . .
Issuing the SELECT TCPXLAT Command from

the IUI . . . . . . . . . . . . . . 138
Issuing the SELECT TCPXLAT Command with
the Batch Interface. . . . . . . . . . . 138
SELECT TCPXLAT Command Format . . . . 139
. 137
141
141
142
143
145
146
146
147
147
149
150
150
151
151
152
153
153
154
155
155
156
156
156
157
157
162
163
163
Chapter 1. Introduction to Sterling Connect:Direct commands

Use Sterling Connect:Direct commands to submit and manipulate Processes stored
in the Transmission Control Queue (TCQ). For example, you can select, delete, and
suspend Processes by using Sterling Connect:Direct commands.
You can use either of the following two methods to issue commands:
Method
Description
Batch Interface
Enables you to issue Sterling Connect:Direct commands with the

DGADBATC program in a batch environment. See Introduction to the
Batch Interface for more information about how to use the Batch
Interface.
Interactive User
Provides easy-to-use command entry through fill-in-the-blank screens.

The Interactive User Interface (IUI) is an ISPF Dialog online interface.
See Introduction to the Interactive User Interface (IUI), for more
information on how to use the IUI.
Some command options which you can select through the IUI do not have a batch
equivalent. The documentation notes these exceptions in option descriptions.
Supported commands
The following table lists Sterling Connect:Direct commands, which perform various
administrative and user functions.
Command
IUI
Function
CHANGE PROCESS
CP
Modify a Process in the TCQ
DELETE PROCESS
DP
Remove a Process from the TCQ
DELETE TYPE
DT
Delete a record from the Type file (both a user and

administrative task)
DELETE USER
DU
Delete a user from the Authorization file

(administrative task)
FLUSH PROCESS
FP
Terminate an Executing Process (both a user and

FLUSH TASK
TF
Remove a task from the Execution queue

INQUIRE1
INQ
View information about Sterling Connect:Direct

DTF status
INQUIRE SNMP
INQ
SNMP
Display SNMP Trap Table
INSERT TYPE
IT
Insert a record in the Type file (both a user and

INSERT USER
IU
Add a user to the Authorization file

MODIFY
MD
Run diagnostics and modify initialization

parameters (administrative task)
SELECT MESSAGE
SEL MSG
Display message detail using message ID
Command
IUI
Function
SELECT NETMAP
NM
Display node from the network map file
SELECT PROCESS
SP
Examine a Process in the TCQ
SELECT STATISTICS
SS
Examine records in the Statistics Log
SELECT TASK
TS
Display Sterling Connect:Direct system tasks

status (administrative task)
SELECT TCPXLAT
NM
Translate TCP/IP host names - addresses
SELECT TYPE
ST
Examine the records in the Type file (both a user

and administrative task)
SELECT USER
SU
Examine user authorization (administrative task)
SIGNON
Connect to Sterling Connect:Direct DTF
SIGNOFF
Terminate a connection to the Sterling

Connect:Direct DTF
STATISTICS
STAT
Perform statistics functions (administrative task)
STOP CD
SN
Stop Sterling Connect:Direct operation

SUBMIT
SB
Submit a Process for execution
SUSPEND PROCESS
SUS
Suspend Process execution
SWAP NODE
SW
Swap to another Sterling Connect:Direct node
UPDATE NETMAP
UNM
Update the network map file (administrative task)
UPDATE TYPE
IT
Update a record in the Type file (both a user and

UPDATE USER
IU
Change user privileges (administrative task)
Writing Sterling Connect:Direct commands

A Sterling Connect:Direct command is a string of characters that conveys your
requests to the Sterling Connect:Direct Data Transmission Facility (DTF) for
execution. You write these commands by using a unique syntax called the Sterling
Connect:Direct native format.
If you are using the batch interface, operator interface, or your own user-written
application, you write the commands in this native format. If you are using the
IUI, Sterling Connect:Direct builds the commands in the format for you.
Native format
The following table shows the structure of a Sterling Connect:Direct command in
its native format.
Label
Command
Parameters and Subparameters
The following table explains each command component:
Component
Description
Label (optional)
You can optionally identify your Sterling Connect:Direct command

through use of a label. A label must begin in position 1 and consists of
a 1-8 character alphanumeric string, with the first character alphabetic.
Component
Description
Command
The command itself specifies the Sterling Connect:Direct function

requested and must begin after position 1.
Use one or more blanks to separate the command from the parameters
which follow it.
Parameters or
Subparameters
Parameters or subparameters specify further instructions for the

command. Separate your parameters by one or more blanks.
Parameters can be either keyword or positional.
Keyword parameters are usually followed by an equal sign and can
have a set of subparameters. An example of a keyword parameter is
CASE in the following command.
SIGNON NETMAP=network.map.name CASE=Yes|No
You must type positional parameters in a specific order, with commas
replacing any parameter not typed. These parameters are always on the
right of the equal sign. Enclose positional subparameters in
parentheses, with the parentheses preceded and followed by blanks or
commas.
In the following command USERID is an example of a keyword
parameter, and ID,pswd,newpswd are examples of positional
subparameters:
SIGNON USERID=(ID,pswd,newpswd)
A positional parameter or the variable information in a keyword
parameter is sometimes a list of subparameters. Such a list can include
both positional and keyword parameters.
Command example
The following CHANGE PROCESS command changes a preexisting Process named
PAYROLL so that the new destination node is DALLAS1 and the Process executes
every Friday:
CH PROC
WHERE (PNAME=PAYROLL)
DEST=DALLAS1
RETAIN=Y
STARTT=(FR)
Command syntax
This section describes the syntax used to construct Sterling Connect:Direct
commands and Processes.
For a complete description of Process syntax and examples, see the IBM Sterling
Connect:Direct Process Language Reference Guide.
Asterisks
Use asterisks to indicate generic specifications of parameters in the SELECT
commands. With generics, you request information by specifying just a single
asterisk (*) or a character string plus an asterisk.
To examine records for users whose user IDs begin with ST, specify the following
parameter:
USERID=ST*
Commas
Commas function to separate items within a list (except in the case of symbolic
substitution. Refer to Symbolic Substitution), and to control the order of values
specified as positional parameters. You must use a comma to indicate omission of a
positional parameter. In the following example, the omission of the pswd
subparameter is indicated by the extra comma.
SIGNON USERID=(ID,,newpswd)
Continuation Marks
A command can continue across multiple lines. Use the hyphen (-), preceded and
followed by a space, to indicate that the command continues on the following line.
The hyphen can appear anywhere in positions 3-79. The following command is
continued on a second line.
CHANGE PROCESS WHERE (PNAME=PAYROLL) DEST=DALLAS1
Parentheses
In the following example, parentheses enclose lists and associate a group of values.
SIGNON USERID=(MYUID1,MYPSWD)
Symbolic Substitution
Use symbolic substitution to substitute information in a Sterling Connect:Direct
Process. The substitution is represented by an ampersand (&) plus 1-8
alphanumeric characters. In the following example, the value for &DATA is
resolved when you submit the Process.
DSN=&DATA
If you have multiple symbolics, separate them with one or more spaces.
Single and Double Quotation Marks

The rules for using single and double quotation marks are:
v Single-quote strings allow the parsing of parameters as typed.
v Double-quote strings allow the resolution of symbolic substitution in a quoted
string.
The following example shows the use of single quotation marks to enable you to
embed special characters or blanks within a parameter or subparameter value.
SIGNON PACCT=JOB FOR SYSMAINT,DEPT.27
The following example shows the use of double quotation marks to allow for the
resolution of symbolic substitution.
SIGNON PACCT="JOB FOR SYSMAINT,DEPT. &DEPND"
Single quotation marks are not valid for symbolic substitution in a Sterling
Connect:Direct command but can be used with a keyword parameter in a Process
statement (refer to the IBM Sterling Connect:DirectProcess Language Reference Guide
For example, the following SUBMIT Process command, which uses single
quotation marks:
SUB PROC=DCB HOLD=YES &DCB=DCB=(LRECL=80,BLKSIZE=3120,RECFM=FM)
results in the following invalid Process.

SUB PROC=DCB HOLD=YES
&DCB=DCB=(LRECL=80,BLKSIZE=3120,RECFM=FB)
The following example which uses the same Process information as the example
above but this time with double quotation marks:
SUB PROC=DCB HOLD=YES &DCB=DCB=(LRECL=80,BLKSIZE=3120,RECFM=FM)
resolves to:
SUB PROC=DCB HOLD=YES
&DCB=DCB=(LRECL=80,BLKSIZE=3120,RECFM=FB)
Comments
Comments allow you to include descriptive information within a command.
Comments are available for your convenience and do not affect Sterling
Connect:Direct. Use the following formats for comments:
v Preceded by a slash-asterisk (/*) and followed by an asterisk-slash (*/).
v An asterisk (*) in position 1, followed by the comment.
All three of the following lines are valid comments, indicating that the SIGNON
command labeled DSIGN signs on to the DALLAS node.
/* SIGN ON TO DALLAS */
*SIGN ON TO DALLAS
DSIGN SIGNON NODE=DALLAS /*DALLAS*/
Concatenation
Use the double bar ( || ) to concatenate, or link together, character strings. You
must precede the double bar and follow it with a blank. Use the double bar to join
a long value that continues over multiple records. For example, you can type the
following command.
PACCT=JOBACCTDATA ||
WITHNOBLANKS
The vertical bar is x'4F'.

Sterling Connect:Direct resolves your command to the following format:
PACCT=JOBACCTDATAWITHNOBLANKS
Special Characters
Certain characters cause Sterling Connect:Direct to take special actions. These
special characters are the hyphen (-), double bar (||), ampersand (&), and the
Sterling Connect:Direct delimiters. The following table lists the delimiters
recognized by Sterling Connect:Direct.
Delimiters
Description
blank
<
less than sign
>
greater than sign
asterisk
Delimiters
Description
open parenthesis
close parenthesis
not sign
slash
backslash
comma
period
'
single quotation mark
"
double quotation mark
equal sign
opening brace
closing brace
opening bracket
closing bracket
Special Purpose Bracketing

You must often maintain special characters as part of a string. To maintain special
characters, enclose the string in bracketing characters. Bracketing characters are
backslashes (\), single quotation marks ('), and double quotation marks (").
Bracketing backslashes are indicators of special processing of a character string.
Sterling Connect:Direct does not maintain them as part of the string at its final
resolution. Use bracketing backslashes to:
v Continue a string containing special characters across multiple lines
v Ensure that quotation marks within the string are maintained
The following is an example of using bracketing backslashes in a command:
PACCT=\DEPT\MIS\ || \602\
Sterling Connect:Direct resolves the command as follows:

PACCT=DEPT\MIS602
Indicating case sensitivity

The CASE parameter specifies whether parameters associated with accounting
data, user ID, password, and data set name in the commands and Processes are
case-sensitive. You can make this designation at the signon level for all commands
that are issued for the session that is established by the signon, and at the
command level.
The following table describes the levels at which you can set the CASE parameter.
Level
Description
Session
The CASE parameter of the SIGNON command indicates if

commands entered during this session are case-sensitive. The
default value is NO. You can override this setting at the command
level.
Level
Description
Individual Command
You can change the CASE parameter for an individual command

and override the session case sensitivity as follows:
v In the Sterling Connect:Direct for z/OS IUI, the CASE
parameter is usually indicated on the IUI by the following
words: DO YOU WANT VALUES FOR THIS REQUEST TO
BE CASE SENSITIVE? ==> Reply Y or N to this question. The
value for the CASE parameter stays in effect as long as you
reuse the same panel. When you change panels, the value
reverts to the session default.
v In native command mode, such as used in the Batch Interface,
you must designate your override on each command record if
you want to override the CASE parameter of the SIGNON
command.
Process
For commands that refer to Processes already in the TCQ, only the
CASE parameter applies to the fields in the command. For
commands that refer to Processes that are not yet in the TCQ, the
case sensitivity applies to the Process statements.
Indicating selection criteria

Use the WHERE parameter to specify which records to select, change, or delete
based on subparameters, such as Process name or Userid.
Selection subparameters are optional; however, you must specify at least one.
These subparameters are special in that they identify which records are selected for
the command activity defined by the other parameters.
Use the WHERE parameter to indicate selection criteria for commands which affect
Process, Task, Type, User, and Statistic records. The command function applies to
all records which match the selection criteria.
For example, in the CHANGE PROCESS command, you can use the WHERE
parameter with its PNUMBER subparameter to select a list of Processes by number
and release all of them through the RELEASE parameter.
In the IUI, the WHERE parameter is represented by the list of selection criteria
which precedes the command parameters themselves. For example, you see the
following on the CHANGE PROCESS screen:
PROCESS NUMBERS:
==> _____ ==> _____
==> _____ ==> _____
Additionally, you see lists for Process name and submitter to indicate the selection
criteria. The Sterling Connect:Direct IUI builds the WHERE parameter for the
command as it selects the fields from left to right on the screen.
Indicating output destination

The FILE, PRINT, TABLE, and DISPLAY parameters specify the form in which
information is presented when the command produces output.
The following table describes each parameter.
Parameter
Description
FILE
Causes Sterling Connect:Direct to return the output as unformatted

records to the temporary file. You indicate the name of your temporary
file through the TMPDSN parameter of your SIGNON command. See
Using SIGNON through the Batch Interface on page 44, for a
description of the TMPDSN parameter. The statistics record macros in
the Sterling Connect:Direct sample library provide the output record
format.
When Sterling Connect:Direct puts the unformatted records in a
temporary file, other programs can process the records and customize
reports for specific needs. You can use this functionality to process
statistics records. You can archive a statistics file each day with a
Generation Data Group (GDG). The Sterling Connect:Direct product
provides sample job streams that extract statistics on a daily basis.
PRINT
Routes output of the command to the destination specified in the

PRINT keyword of the SIGNON command. See Using SIGNON
through the Batch Interface on page 44, for a description of the PRINT
parameter.
TABLE or
DISPLAY
Stores the output of the command in the Sterling Connect:Direct

temporary file or file specified in the TMPDSN parameter and displays
it upon successful completion of the command. (For more information
on the TMPDSN parameter, see Using SIGNON through the Batch
Interface on page 44.) The output is usually in tabular format. You can
browse the output by using such commands as UP, RIGHT, or FIND.
Press the PF1 key for Help on how to browse the file.
Some screens offer additional output format, such as summary tables. These
options are listed along with the display, file, and print options.
Chapter 2. The batch interface

You request Sterling Connect:Direct services in the batch environment through the
batch interface program, DGADBATC.
When you submit a job stream that contains Sterling Connect:Direct commands
such as SYSIN input, DGADBATC reads the input data stream and processes the
requested functions. DGADBATC supports all Sterling Connect:Direct commands.
Batch interface job requirements

Batch interface jobs must meet certain requirements.
v You cannot use Process statements in the job stream. Use the SUBMIT command
with a preexisting Process that contains Process statements. Unless MAXDELAY
is used, DGADBATC processing of the SUBMIT is asynchronous. The batch job
is notified of a successful SUBMIT, but not whether the PROCESS itself is
successful.
v For DGADBATC, specify a region size of 0 megabytes (REGION=0M), especially
if you specify MAXDELAY. If you specify a different region size, the
DGADBATC job can ABEND with an 878 code.
v The Processes that you submit must be in the Sterling Connect:Direct Public
Process Library, allocated to the DMPUBLIB DD statement in the DGADBATC
JCL. If the Process is not in the Sterling Connect:Direct Public Process Library,
use the DSN parameter of the SUBMIT command to indicate the location of the
Process. See Building, Modifying, and Submitting Processes, for the DSN
parameter description.
The Sterling Connect:Direct commands that you use in the batch job stream
must follow the syntax that is outlined in Writing Sterling Connect:Direct
Commands.
v If you are not using the Extended Submit Facility (ESF), the DTFs that you sign
on to must be active when you submit the DGADBATC job.
v You can specify ESF as a SIGNON command parameter. You can only issue
SIGNON, SIGNOFF, and SUBMIT commands by using ESF. ESF is only available
for Processes you submit on the local node.
Processing rules
The following rules apply to Sterling Connect:Direct commands and options in the
DGADBATC job stream.
v The first command in the job stream must be a SIGNON command.
v The maximum command string length is 4,096 bytes. Each new Sterling
Connect:Direct command in the job stream must start on a separate line. You can
split a command across more than one line by using the continuation mark.
However, the first word or string of the next command must start on a new line
as shown in the following example.
SIGNON USERID=(LYNN) NODE=CD.BOSTON
SEL STAT WHERE (PNUM=24)
SIGNOFF
Sample job stream to run the batch interface

The following example shows a sample job stream to run the DGADBATC
program. The job stream is located in $CD.SDGAJCL(DGADBATC).
//JOBNAME JOB (ACCNTNG),PROGRAMMER,TIME=2,CLASS=A,
//
MSGCLASS=A
//DGADBATC EXEC PGM=DGADBATC,REGION=0M,PARM='YYSLYNN'
//STEPLIB
DD DISP=SHR,DSN=$CD.SDGALINK
//DMNETMAP DD DISP=SHR,DSN=$CD.NETMAP
//DMPUBLIB DD DISP=SHR,DSN=$CD.SDGAPROC
//DMMSGFIL DD DISP=SHR,DSN=$CD.MSG
//DMPRINT
DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSIN
DD *
SIGNON USERID=(USERID,PASSWORD)
SUBMIT PROC=COPY SNODE=CD.NODE.B HOLD=NO
&NODE=PNODE
&DSN1=DATASET1
&DSN2=DATASET2
&DISP1=RPL
&DISP2=CATLG
&COMPRESS=COMPRESS
SEL PROC WHERE (QUEUE=A) TABLE
SIGNOFF
/*
The following example shows the COPY Process submitted in the previous
example as it is displayed in the Sterling Connect:Direct Public Process Library,
$CD.SDGAPROC:
COPY
STEP1
PROCESS
COPY
FROM(&NODE DSN=&DSN1
DISP=SHR)
TO (DSN=&DSN2 DISP=(&DISP1,&DISP2)) &COMPRESS
DDNAMES for DGADBATC

The DGADBATC program has both required and optional ddnames.
The following table describes the required and optional ddnames for the
DGADBATC program shown in the sample job stream example.
DDNAME
Description
STEPLIB
Indicates the location of the library that contains the Sterling Connect:Direct
load modules. This DD statement is required, unless the data set is in
linklist.
DMNETMAP Indicates the name of the network map for the node you are signing on to.
You can also specify this name through the SIGNON command NETMAP
parameter. If you use both methods, the network map file name specified
on the SIGNON command takes precedence. This DD statement is optional.
10
DMPUBLIB
Indicates the library that contains the Sterling Connect:Direct Processes. This
DD statement is required.
DMMSGFIL
Indicates the Sterling Connect:Direct message file that contains Sterling

Connect:Direct messages. This DD statement is required.
DMPRINT
Indicates the destination of the job output from DGADBATC that collects
output messages such as error messages. This DD statement is required.
Always check DMPRINT output for verification of the processing that
occurred.
DDNAME
Description
SYSPRINT
Indicates the destination of the job execution messages. This DD statement

is optional.
NDMCMDS
Use to test new job streams. If specified, it prints an image of each

command sent to Sterling Connect:Direct after processing all symbolic
substitution and parameter overrides. This DD statement is optional.
SYSIN
Indicates the location of the Sterling Connect:Direct commands. You can

represent it as a sequential file, PDS member, or instream data. If using a
file, its DCB should be RECFM=FB,LRECL=80. This DD statement is
required.
DGADBATC EXEC parameters

The DGADBATC EXEC parameters identify optional output formatting routines.
The characters in the PARM keyword in the DGADBATC EXEC statement are
required parameters. The output is displayed in the data set defined by DMPRINT.
In the following table which lists the positional DGADBATC EXEC parameters, Y
stands for yes, N for no, S for short text, and L for long text. No default values are
used.
Position
Value
Description
Display the command string that executed.
Do not display the command string that executed.
Display the API return code and message ID.
Do not display the API return code and message ID.
Display short message text when the API sends a return code of
zero.
Display long message text when the API sends a return code of
zero.
Do not display message text when the API sends a return code of
zero.
Display short message text when the API sends a non-zero return
code.
Display long message text when the API sends a non-zero return
code.
Do not display message text when the API sends a return code
greater than zero.
Display the data that generated in the temporary file.
Do not display the data that generated in the temporary file.
Reserved
Reserved
Prints output from a SELECT STATS command to DMPRINT when

a MAXDELAY Process fails with a return code other than 52.
DGADBATC return codes with DGADCHLA

DGADBATC communicates with the Sterling Connect:Direct API through a
high-level application interface program, DGADCHLA. The DGADCHLA program
11
detects error situations while processing commands for DGADBATC, and issues
special return codes based on these situations.
The return code from DGADBATC reflects the highest return code of all
commands processed.
If you receive a return code of 4 or 8, check the DMPRINT DD output for the exact
error that is encountered during command processing to DGADBATC.
A return code of 8 normally indicates an invalid parameter or keyword. A return
code of 4 indicates that DGADCHLA found nothing for the command. For
example, you could receive a return code of 4 if you issued a SELECT STATISTICS
command for a Process with no statistics.
If you receive a DGADBATC return code greater than 8, check return codes for
error information.
Return Code Description
0000000C
A session is lost in a multiple session environment.
00000010
The master session is lost.
00000014
The master session is signed off successfully.
0000001C
A non-master signon failed.
00000020
High-level interface program, DGADCHLA, received an invalid number of

input parameters.
00000024
The output specification included an invalid parameter.
00000028
Invalid pointer to the UICB is passed to DGADCHLA.
For more information on multiple session environments, see Sample Job Stream to
Run the Batch Interface.
Using the MAXDELAY keyword parameter to synchronize submitted

Processes
You can synchronize submitted Processes by coding the MAXDELAY keyword
parameter in either the SUBMIT command or the PROCESS statement.
To suspend the execution of the DGADBATC job step until the submitted Process
either completes or a specified interval of time elapses, use the MAXDELAY
keyword.
For a detailed description of the MAXDELAY parameter, See the Submit Command
in the Connect:Direct Process Language help.
Important: Because of the following restrictions, you might want to code
MAXDELAY in the SUBMIT command instead of the PROCESS statement:
v If you code MAXDELAY in a PROCESS and submit it through the IUI, your TSO
session hangs until the Process completes.
v The user who performs the SUBMIT command cannot see the MAXDELAY
value that is specified in the PROCESS statement and wonders what is holding
up the session.
12
v If you use the MAXDELAY PROCESS statement keyword, the message SCBI221I
MAXDELAY not supported for ESF submits is displayed when the DTF is down
and the Process does not submit.
To place a job stream in a wait status for a specified period and set return codes
that indicate step or task completion, use the DGADWAIT program as a batch step
or a RUN TASK. For more information, see Run Task Wait Program (DGADWAIT).
The following example shows the MAXDELAY keyword that is coded in the
SUBMIT command.
//SYSIN
DD *
SIGNON USERID=(USER01,PASSWRD)
SUBMIT PROC=PROCAAA MAXDELAY=UNLIMITED
SIGNOFF
/*
You can also place the MAXDELAY keyword in the PROCESS statement for
PROCAAA, as in the following example.
PROCAAA
STEP01
PROC SNODE=REMOTE.NODE.B MAXDELAY=UNLIMITED

COPY TO (DSN=USER01.TESTDATA.OUTPUT
DISP=RPL
SNODE)
FROM (DSN=USER01.TESTDATA.INPUT
DISP=SHR
PNODE)
13
14
Chapter 3. The Interactive User Interface (IUI)

Issue Sterling Connect:Direct commands using the IUI through two menus.
Menu
Description
The Primary
Options Menu
Enables you to invoke screens where you can create and submit
Processes, view statistics about your Processes, control your Processes
in the Transmission Control Queue (TCQ), view your Sterling
Connect:Direct environment, access the message file, sign on, swap
nodes, and sign off Sterling Connect:Direct. This option is available to
all users, and is described in this book.
The
Administrative
Options Menu
Enables the Sterling Connect:Direct product administrator to perform

maintenance to the Type file, the Authorization file, and the network
map and to perform functions such as selecting and flushing tasks,
initializing traces, typing native commands, displaying storage
utilization, requesting traces, and stopping Sterling Connect:Direct.
Note: You can also use the IBM Sterling Connect:Direct Browser User Interface to
perform some of the procedures in this chapter.
Primary Options Menu

The Primary Options Menu contains the Sterling Connect:Direct functions which
are available to most users.
CSG.PROD390
PRIMARY OPTIONS MENU
CMD ==>
Connect:Direct SIGNON process completed.
SELECT ONE OF THE FOLLOWING:
More:
+
CF - COPY A FILE
***********************
SB - SUBMIT A PREDEFINED PROCESS
*
*
DF - DEFINE A PROCESS USING ISPF EDIT
* TODAY: 02.24.2011 *
SS - VIEW STATISTICS FOR A COMPLETED PROCESS
* TIME: 09:04
*
MB - SUBMIT A BATCH TO Connect:Enterprise for z/OS *
*
CP - CHANGE CHARACTERISTICS OF A PROCESS
***********************
DP - DELETE A NON-EXECUTING PROCESS
FP - FLUSH AN EXECUTING PROCESS
SP - VIEW DATA ABOUT AN EXECUTING PROCESS
___________________________________________________________________
|
|
|
Licensed Materials - Property of IBM
|
|
5655-X01 Copyright IBM Corp. 2011
|
|
All Rights Reserved
.
|
|
IBM is a Trademark of International Business Machines
|
|
|
|__________________________________________________________________|
To request a function, type its option identifier on the command line (CMD==>)
and press Enter. The following options enable you to create and submit Processes
to the TCQ:
Option
Description
CF
Displays the main Copy File Menu where you can set up a COPY Process.
15
Option
Description
SB
Displays the Submit Process screen where you can submit a predefined Process.
DF
Displays the Process Definition Screen where you can define or update a
Process using the ISPF edit function and then submit the Process.
See Building, Modifying, and Submitting Processes for more information.

The following option enables you to view statistics related to completed Processes:
Option
Description
SS
Displays the Select Statistics screen where you can examine the system
statistics log records with search criteria applied and select the output to go to
a file, table, or printer. See Process Results and Statistics for more information
on the Select Statistics screen.
The following options enable you to delete, flush, view, suspend, and change
Processes in the TCQ:
Option
Description
CP
Accesses the Change Process screen where you can change the priority and
class of a Process and the status of the Process in the TCQ. See Modifying a
Process in the TCQ with CHANGE PROCESS for more information on the
Change Process screen.
DP
Displays the Delete Process screen where you remove a nonexecuting Process
from the TCQ.
FP
Displays the Flush Process screen where you can remove an executing Process
from the TCQ.
SP
Displays the Select Process screen where you view the status of Processes
submitted (placed in the TCQ) for execution. See Controlling Processes with
Commands for information.
PS
Displays the Suspend Process screen where you put an executing Process in the
Hold TCQ. See Controlling Processes with Commands for information.
The following options enable you to view your Sterling Connect:Direct

environment:
16
Option
Description
MSG
Displays the Message Maintenance screen where you can display Sterling
Connect:Direct messages or print a summary or full report of the Sterling
Connect:Direct message file. See Viewing and Printing Messages Using
Different Criteria for more information on the Message Maintenance screen.
SD
Displays the Signon Defaults screen where you can examine and change your
signon default values. See Signing On to Sterling Connect:Direct for z/OS for
more information on the Signon Defaults screen.
NM
Displays the Select network map screen, where you choose for display or print
the defined nodes from the network map file and translate TCP/IP host names
and network addresses.
Option
Description
WHO
Displays the User Information screen, which indicates your user ID, user node,
version, release, maintenance level of Sterling Connect:Direct and file
information about your current session. See Signing On to Sterling
Connect:Direct for z/OS for more information on viewing current sign on
parameters.
AUTH
Displays the User Authorization screen. This screen displays commands you
are authorized to use. See Displaying Your User Authorization for more
information.
The following options enable you to sign on and swap among multiple sessions:
Option
Description
MS
Displays the Multiple Session Signon screen where you sign on to another DTF
session. See page 46 for information.
SW
Displays the Swap/Display User Sessions screen where you view all the
multiple sessions that you are signed on to and swap sessions. See Signing On
to Multiple Sessions for more information on the Multiple Session Signon
screen.
The following options display other menus:

Option
Description
SPF
Displays an ISPF/PDF session, one level beneath Sterling Connect:Direct

panels. See Navigating the Interactive User Interface for information on
branching to an ISPF/PDF session.
ADMIN
Displays the Connect:Direct Administrative Options Menu with command

options used for administering the system.
Navigating the Interactive User Interface

You can move from screen to screen with branch commands and function keys.
Using Branch Commands

Branch commands enable you to navigate quickly to a specific screen without
returning to the Menu. You can type the branch command on the command line at
the top of the screen (CMD==>) or on any input line preceded by ==>. To execute
the branch, type = followed by the ID of the screen you want to branch to and
press Enter.
For example, to go to the Select Process (SP) screen, type =SP on the command line
and press Enter.
Note: The equal sign (=) is not required before an option on the command line of
the Signon screen or the Primary Options Menu.
The following table describes two additional branch commands that you can use.
17
Command
Description
=ADMIN.xx
Enables you to move to an administrative screen from a primary

screen. For example, to branch from the WHO screen (which is an
option of the Primary Menu) to the INQ screen (which is an option of
the Administrative Menu), type =ADMIN.INQ at the command line of
the WHO screen.
where xx is the
screen ID
SPF.x
where x is the
SPF option that
you want to
display
The SPF option on the Primary Options Menu branches to the

ISPF/PDF session, one level beneath the Sterling Connect:Direct panels.
If you want to bypass the ISPF/PDF menu, type the SPF command
with a period and the option. For example, to use the BROWSE
function within ISPF/PDF, type SPF.1 on the command line. The SPF
command is valid on each Sterling Connect:Direct screen command
line.
Using the PF Keys

The PF keys listed in the following table are some of the programmed default
definitions that you can use with Sterling Connect:Direct screens. The ISPF
user-defined PF keys are supported.
Key
Result
PF1
Displays online field Help or long error message
PF3
Returns to the previous screen
PF4
Returns to the Primary Options Menu
PF7
Scrolls up
PF8
Scrolls down
PF10
Scrolls right
PF11
Scrolls left
Browsing the IUI Display

The TABLE or DISPLAY parameters which are options at the bottom of most
Selection screens specify that the output of the selection command is stored in the
Sterling Connect:Direct temporary file and then displayed upon successful
completion of the command. The output is usually in tabular format. Use the
commands, UP, RIGHT, or FIND, to browse the output. Press the PF1 key to see
extensive Help on how to browse the file.
Displaying Your User Authorization

Use the User Authorization screen to determine commands you are authorized to
execute. To access the screen, select the AUTH option from the Primary Options
Menu.
18
CSG.PROD390
USER AUTHORIZATION
13:30
CMD ==>
AUTH COMMAND
AUTH COMMAND
----------------------------------------------------1) YES - CHANGE PROCESS
15) YES - SELECT TASK
2) YES - DELETE PROCESS
16) YES - SELECT TYPE
3) YES - DELETE TYPE
17) YES - SELECT USER
4) YES - DELETE USER
18) YES - SUBMIT PROCESS
5) YES - FLUSH PROCESS
19) YES - SUBMIT WITHIN PROC
6) YES - FLUSH TASK
20) YES - SUSPEND PROCESS
7) Y/Y - INSERT/UPDATE TYPE
21) YES - STAT COMMAND
8) Y/Y - INSERT/UPDATE USER
22) YES - EVENT COMMAND
9) YES - MODIFY (TRACE)
23) YES - VIEW PROCESS
10) YES - STOP Connect:Direct
24) YES - PERFORM CRC OVERRIDES
11) YES - UPDATE NETWORK MAP
25) NO - CONFIRM DELETE
12) YES - SELECT NETWORK MAP
26) NO - CONFIRM DEL OFF
13) YES - SELECT PROCESS
27) YES - SECURE+ ADMIN
14) YES - SELECT STATISTICS
28) NO - UPDATE INITPARM
YES or Y means you are authorized, NO or N means you are not authorized, and
SUB means you are authorized only if you submitted the Process.
To branch to an authorized function, type the corresponding number on the
command line.
Getting Help
Sterling Connect:Direct provides a Help facility which describes the parameters
that you can type through the IUI.
Procedure
v Access the Help information by typing HELP on the command line and press
Enter or pressing the PF1 key.
v Press Enter to continue viewing the Help screens.
v When you have viewed the screens, you can either press PF1 to continue to the
tutorial or press PF3 to return to the screen you branched from.
Operator Tables
The Operator Table is available only under the IUI. This display enables you to
monitor and control Processes. It is accessed through the SELECT PROCESS
command and provides a summary of PNODE Processes in the TCQ. See Viewing
and Controlling a Process through the Operator Table for a description and
samples of the Operator Table.
19
node.name
Row 1 to 6 of 6
-------------------------------OPERATOR TABLE------------------==> Q
SCROLL ===> PAGE
OPTION
PNAME
PNUMBER
SUBMITTER.NODE-- OTHER.NODE------ QUEUE
SERVER
USERID
------------------------------------------------------------------------------SEND100M
18
CD.NODE1
CD.STD45
EX EX
USER01
SEND50K
20
CD.NODE2
10.20.129.151
P EX
USER01
COPYPAY
25
CD.NODE3
CD.STD44
P EX
USER01
BKUPDSK1
2
CD.NODE4
10.20.129.141
P EX
USER01
BENCH50
13,218
CD.NODE5
CD.STD45
P EX
USER01
COPYCF
21
CD.NODE6
CD.STD45
HO HI
******************************* Bottom of data ********************************
USER01
You can press Enter to refresh the display and monitor the progress of the
Processes displayed on the screen. The following table describes the commands
that you can issue from the Operator Table.
Command
Description
Hold
Delete
Release
Suspend
Flush
View Processes
Show Detail
Type the option you want in the OPTION column next to the name of the Process
as shown in the previous screen.
Note: The Executing Queue version of the Operator Table displays the executing
Processes only; therefore, the options available to it are limited to the Suspend (P)
and Show detail (S) only.
Messages
You may encounter two types of messages: ISPF/PDF and Sterling Connect:Direct
messages.
20
Message Type
Description
ISPF/PDF
messages
Display at the top of the screen when the value you typed for a field does
not pass the editor. You get this kind of message if, for example, you type
an alphabetic character in a numeric field. Press PF1 to see a longer
explanation of the error or type HELP on the command line and press
Enter.
Message Type
Description
Sterling
Connect:Direct
messages and
sense codes
Contain a short and long text which explain an error you get when you
submit your command. This type of error is indicated by a message ID
with the format xxxxnnnx, for example, SVSL003I. You get this error, if,
for example, you type an invalid Process name on a SELECT PROCESS
command.
Sterling Connect:Direct generates a sense code to indicate a connection
error involving a netmap. The format for a sense code is SENSnnnn where
nnnn is the four-digit number representing the sense code.
Message Example
In the following example, the user typed ABC for Process Number, a numeric field,
resulting in the message PROCESS NUMBER in the upper right corner. Pressing
PF1 produces the longer message "ABC" IS INVALID...
node.name
SELECT PROCESS
PROCESS NUMBER
CMD ==> O
hh:mm
"ABC" IS INVALID; MUST BE IN THE RANGE 0 - 199,999.
CMD:
O ... OPERATOR TABLE S ... OPERATOR TABLE/EXEC QUEUE STATUS
P ... PRINT REPORT
D ... DISPLAY REPORT
V ... VIEW PROCESS
QUEUE:
==> _ (A-ALL,W-WAIT,E-EXECUTE,H-HOLD,T-TIMER)
PROCESS NUMBERS: ==> ______
==> ______
==> ______
==> ______
PROCESS NAMES:
==> ________
==> ________
==> ________
==> ________
SERVER NAMES:
==> ________
==> ________
==> ________
==> ________
STATUS:
(HO,HR,HI,HE,HC,HP,HS,RH,RA,WC,WX,WT,H,R,W)
==> __
==> __
==> __
==> __
DESTINATION NODES:
==> ________________
==> ________________
==> ________________
==> ________________
USER ID:
NODE ID:
==> ________________________________________________________________
==> ________________
==> ________________________________________________________________
==> ________________
DO YOU WANT VALUES FOR THIS REQUEST TO BE CASE SENSITIVE? ==> NO
The following is an of the short text message that is displayed at the top of the
screen.
No process(es) found matching the search criteria.
The long text provides a more detailed explanation of the message and can also
include the system action and a suggested response. Press PF1 to see the long
explanation of the error or type HELP or M on the command line and press Enter.
The following figure shows a sample message.
node.name
Connect:Direct MESSAGE DISPLAY
CMD ==>
MSGID ==> SVSL003I
MODULE ==> DMVSOPEN
Copy requested DISP=(,CATLG) to already cataloged dataset.
The PROCESS COPY step requested a DISP=(,CATLG) on the TO
clause of the COPY statement. The requested dataset already
exists as a cataloged dataset.
System Action. The PROCESS COPY step is terminated with a
completion code of 8.
Response: Either correct the COPY dataset or uncatalog the
existing dataset and re-submit the PROCESS.
hh:mm
21
The Statistics Summary screen, an option of the SELECT STATISTICS command,

also gives you the option of branching to the message screen associated with a
failed Process. Type an M next to the Process name which failed (indicated by an
*), and Sterling Connect:Direct displays the extended message.
Messages in a Sterling Connect:Direct/Plex Environment

In a Sterling Connect:Direct/Plex environment, messages can originate from any
Sterling Connect:Direct Server or from the Sterling Connect:Direct Manager. The
system administrator can define a 2-character message ID that identifies which
Sterling Connect:Direct/Plex member originated the message. This message ID is
displayed after the message number, as in the following example. The message ID
is highlighted in bold in this example.
SVTM055I
SVTM055I
SVTM036I
SVTM036I
S1
S1
S1
S1
SESSION
SESSION
PROCESS
PROCESS
(001) ESTABLISHED WITH

(001) ESTABLISHED WITH
STARTED
MVS2MVST(
STARTED
MVSM2VST(
SNODE=SC.DUB.OS390
PNODE=SC.DUB.OS390
1) PNODE=SC.DUB.OS390
1) SNODE=SC.DUB.OS390
The system administrator defines the message ID using the CDPLEX.MSGID

initialization parameter. For more information, see Customizing Sterling
Connect:Direct in the IBM Sterling Connect:Direct for z/OS Administration Guide and
search for .
Viewing and Printing Messages Using Different Criteria

About this task
You can use the Message Maintenance screen to view or print Sterling
Connect:Direct Message Text. You can display messages by message ID if you need
to look up an error message in your Process statistics, or if you have a batch job
that failed.
Procedure
1. Type DIR at the COMMAND prompt at the bottom of the screen to display the
directory of the module messages.
2. From the Primary Options Menu, select option MSG. The MSG command is
available only through the IUI. The following sample screen is a combination of
two panels to show the prefixes used in Sterling Connect:Direct messages:
22
Connect:Direct MESSAGE LOOKUP
2 Members processed
DATE => yyyy/mm/mm

ENTER OPTION ==> _
TIME => hh:mm
==============================================================================
OPTIONS
===========
1 = DISPLAY MESSAGE TEXT BY MESSAGE ID
2 = DISPLAY LIST OF ENTRIES (OPTIONALLY BY MODULE)
MODULE==> ________________________________________________________________
3 = PRINT SUMMARY REPORT
4 = PRINT FULL REPORT
The following is the general basis for C:D messages:
MAINFRAME: z/OS, VM, VSE, Security (ACF2, RACF, TSS), etc.
MESSAGE
MESSAGE
PREFIX
Applies to:
PREFIX
Applies to:
N xxx
CICS API failures
Q xxx
CICS API failures
RACF xxxx Security system MSGs
S xxxxxxx C:D Mainframe msgs
SENS nnnn NETMAP sense code
U nnnn
z/OS User ABEND code
CSPx xxxx Secure Plus
MBCS xxxx Multi-Byte Character Set
NON-Mainframe
MESSAGE
MESSAGE
PREFIX
Applies to:
PREFIX
Applies to:
A xxxxxxx i5/OS or OS/400
CCUP xxxx Control Center
EMSL xxxx HP NonStop or Tandem
FSLD xxxx HP NonStop or Tandem
IOXT xxxx HP NonStop or Tandem
J xxxxxxx C:D for the Web
L xxxxxxx Windows, SI, or Select V xxxxxxx OpenVMS
X xxxxxxx Linux, UNIX, or Stratus
3. Type 1 on the command line and press Enter. The Message Display Screen
appears.
4. Type the message ID and press Enter. (To check a sense code, type SENSnnnn
where nnnn is the four-digit number representing the sense code and press
Enter.) The full text of the message (or sense code) is displayed. In the
following example, the information associated with Message SCBI190I is
shown.
Connect:Direct MESSAGE DISPLAY
DATE => yyyy.mm.dd
TIME => hh:mm
MESSAGE ID==> SCBI190I
MODULE
==> DMCBSUBM
==============================================================================
SHORT TEXT==> Process specified not in process library.
LONG TEXT:
LINE 1 ==> This message may be generated for the following reasons:
LINE 2 ==>
LINE 3 ==> 1) The member specified is not in the public process library
LINE 4 ==>
or in the PDS specified in the DSN= keyword.
LINE 5 ==> 2) The process library has not been properly concatenated.
LINE 6 ==>
LINE 7 ==>
LINE 8 ==>
LINE 9 ==>
LINE 10==> SYSTEM ACTION: Return to invoker with RC=8.
LINE 11==>
LINE 12==> RESPONSE: Verify the above is correct and resubmit process.
COMMAND ===> ________ ENTER DIR TO DISPLAY THE DIRECTORY
Viewing a Message List

You can display a list of all Sterling Connect:Direct messages or a list of messages
generated by a module.
23
Procedure
1. From the Primary Options Menu, select option MSG.
Note: The MSG command is available only through the IUI.
2. Type 2 on the command line, specify a Module (optional), and press Enter. The
Message Summary screen appears. (If you do not specify a module name, all
messages are displayed.) In the sample below, the module, DMINIT2, was
specified.
------------------Connect:Direct MESSAGE SUMMARY------------------ Row 1 of 31
CMD ==>
SCROLL ===> PAGE
MSG ID
MODULE MESSAGE
CSPN010E DMINIT2 SIGNATURE.DSN.BASE Initialization Parameter Invalid
CSPN011E DMINIT2 SIGNATURE.FILE.PAIRS Initialization Parameter Invalid
CSPN012E DMINIT2 SIGNATURE.DSN.BASE and/or SIGNATURE.FILE.PAIRS missing
CSPN013E DMINIT2 SECURE+ Interface Module not found
CSPN116E DMINIT2 PARM FILE VALIDATION FAILURE
CSPN117E DMINIT2 SECURE.DSN IS NOT A VSAM KSDS
CSPN118E DMINIT2 SECURE+ INTERFACE MODULE NOT FOUND
SCFS006I DMINIT2 AUTOLOG OF CMS SERVER FAILED
SITA137E DMINIT2 POSIX Init Parm conflict.
SITA169I DMINIT2 SECURE.DSN Data set not found.
SITA170I DMINIT2 TRACE.BUFFER outside 0-999 range, TRACE.BUFFER=2 assumed.
SITA185I DMINIT2 SITA185I (VSE) TCP.NAME VALUE OVERRIDEN BY SYSPARM.
SITA190I DMINIT2 Secure+ Initialization failed, Secure No Override No
SITA278I DMINIT2 All nodes are quiesced, QUIESCE=YES specified
SITA338I DMINIT2 Asset Protection Failure.
SITA339I DMINIT2 Number of licensed copies has been exceeded.
SITA604I DMINIT2 Invalid option specified for SNA paramater.
SITA607I DMINIT2 SNA=YES but no VTAM APPLID is available.
SITA609I DMINIT2 VTAM services disabled.
SITA610I DMINIT2 Both SNA and TCP are NO, can not continue.
SITA641W DMINIT2 Level of PDSE.SHARING is not supported.
Note: You must specify the old modules names used in versions prior to the
5.1 release of Sterling Connect:Direct for z/OS. For information, go to IBM
Sterling Connect:Direct for z/OS Release Notes and search for Upgrading to Sterling
Connect:Direct for z/OS Version 5.1.
3. Type an S next to the message ID for the full Message Display screen.
Printing Messages
You can print the Sterling Connect:Direct messages file in summary form or in
detail, including the long form of the message text.
Procedure
1. From the Primary Options Menu, select option MSG.
Note: The MSG command is available only through the IUI.
2. Do one of the following:
v Type 3 on the command line for a summary report, and press Enter.
v Type 4 on the command line for a detail report, and press Enter.
Specify the sysout class for the message file print output and the ID for a
remote printer. If you want your output to go to a preallocated data set
instead, specify the name of the data set. You must enclose the data set name
in single quotes and give it the following DCB attributes.
DSORG=PS,RECFM=FB,LRECL=80,BLKSIZE=0
24
Chapter 4. The Application Program Interface

The high-level application-program, DGADCHLA, handles communication
between the Sterling Connect:Direct for z/OS API and any application program
that provides Sterling Connect:Direct with command strings for batch processing.
You can write an application program following the rules described in the
following sections.
You can also process Sterling Connect:Direct command strings by using the
DGADBATC batch interface program. For more information on using DGADBATC,
refer to Sample Job Stream to Run the Batch Interface.
Both DGADCHLA and DGADBATC are in $CD.SDGALINK.
You can design user-written applications that have an interface to Sterling
Connect:Direct. You can write the applications in any computer language,
including PL/I, Assembler, and COBOL. The following samples are in the
$CD.SDGASAMP library:
Application
Name
Description
DGAXSAMP
Assembler language user-written application, called
DGAXPLIS
PL/I language user-written program, called
DGAXCOBS
COBOL language user-written program, called
Note: All API programs run in 31-bit mode and they must call DGADCHLA in
31-bit mode. You can either link your program as AMODE 31, or establish 31-bit
addressability before calling DGADCHLA. See the sample program DGAXSAMP
for an example of establishing 31-bit addressability and returning to 24-bit
addressability after the call to DGADCHLA. Also execute DGADCHLA with a
BASSM rather than a BALR. Macro GENCALL is provided in the sample library to
perform a BASSM. See the sample program DGAXSAMP for an example.
DGADCHLA Program
The DGADCHLA program communicates with the API through a control block
interface called the User Interface Control Block (UICB). DGADCHLA works in the
following sequence:
1. DGADCHLA accepts Sterling Connect:Direct command strings from an
application program and passes the strings to the API.
2. The user-written application requests DGADCHLA to perform output
formatting routines after returning from the API. These formatting routines
display information about the Sterling Connect:Direct command that just
completed processing.
3. After execution of each command, DGADCHLA issues a return code reflecting
the status of API communications.
25
Required Parameters for DGADCHLA

DGADCHLA requires Sterling Connect:Direct to pass three parameters on every
invocation from an application program. The parameters, in order, are the
following:
Parameter
Description
CMDLEN
(first
parameter)
Points to a variable-length character string (up to 4096 bytes) that contains

the string length in the first halfword and the command text in the
remainder of the string. Just as in DGADBATC, the first command string
must be a SIGNON and the last command must be a SIGNOFF. The
following figure shows the command string format.
UICB@
(second
parameter)
Points to a fullword pointer of zeroes, which is filled in with the UICB

address by DGADCHLA when DGADCHLA receives the SIGNON
command from the application program. Information in the UICB can now
be interrogated by the application program, if necessary. The UICB@ field
is cleared and filled again with zeroes when DGADCHLA receives the
SIGNOFF command.
OUTSPECS
(third
parameter)
Points to a 7-character string containing the output format specifications.

The output is written to the file name defined by DMPRINT. Each
specification is one character long.
All output generated as a result of these specifications is routed to a
DDNAME of DMPRINT. No output is created if the DDNAME is not
present.
The following table describes the OUTSPECS output format specifications:

Field
Values
Meaning
Displays the command string

that executed.
Does not display the

command string that
executed.
Displays the API return code

and message ID.
Does not display the API

return code and message ID.
Displays the short message

text when a return code of
zero comes from the API.
Displays long message text

when a return code of zero is
received from the API.
26
Field
Values
Meaning
Does not display message

text when a return code of
zero is received from the
API.
Displays the short message

text when a nonzero return
code comes from the API.
Displays long message text

when a nonzero return code
comes from the API.
Does not display message

text when a return code
greater than zero comes from
the API.
Displays the data generated

in the temporary file.
Does not display the data

generated in the temporary
file.
Displays the string that

identifies UICB fields which
the Extract feature returns
information about.
Does not display the string

that identifies UICB fields
which the Extract feature
returns information about.
Displays a dump of the area

that received output from the
Extract feature.
Does not display a dump of

the area that received output
from the Extract feature.
Prints detailed SELECT

STATISTICS if MAXDELAY
specified and Process fails.
The following example shows the most common specifications for this parameter.
OUTSPECS DC C'YYSLYNNN'
Positions 6 and 7 are not used by DGADCHLA unless the extract feature of
DGADCHLA is used, as explained in the next section.
Extracting Return Codes

If you want the Return Code from the processed Sterling Connect:Direct command,
you must use the extract feature. This feature enables you to extract certain UICB
fields after Sterling Connect:Direct command execution.
To activate the optional extract feature, the program must pass the following
additional parameters to DGADCHLA:
27
Note:
DGADCHLA specifies either the first three required parameters or all eight
parameters which include these parameters related to return codes. If an incorrect
number of parameters is passed, DGADCHLA issues an error message and assigns
a return code of 20. Processing cannot occur during this time.
Parameter
Description
EXTSTRLN
(fourth
parameter)
The UICB extract string.The user-supplied application must set up an

extract string identifying the UICB fields to extract. The string consists
of a halfword length field containing the length of the extract string
(excluding the itself halfword length field), followed by the first UICB
field to extract, a space, the second UICB field to extract, a space, and
so on.
A sample extract string follows:
You can only specify the UICB fields listed in the extract string. If you
encounter an invalid keyword in the string, the extract routine
terminates execution, and no more information is extracted. The
application is informed of the error by means of the EXTRC, EXTMSG,
and INVALKEY parameters. If field 6 of the OUTSPECS parameter is
set to Y, the extract string is written to the file defined by DMPRINT.
EXTAREA (fifth
parameter)
Where the UICB extracted information is placed. The application is

responsible for ensuring that the area is large enough to accommodate
the information requested by the extract string. If field 7 of OUTSPECS
is set to Y, the extract string is written to the file defined by DMPRINT.
The following shows how to calculate required storage for the extract
area necessary for the extract string in the figure shown for the
EXTSTRLN parameter.
EXTRC (sixth
parameter)
A 4-byte binary field containing the extract feature return code.
EXTMSG
(seventh
parameter)
An 8-character field containing an 8-character message ID from the

extract feature.
INVALKEY
(eighth
parameter)
An 8-character field containing an invalid extract string keyword.

DGADCHLA relays the location of the extract string error to the
application in this parameter. This field contains the invalid item in the
extract string if EXTRC is nonzero.
The following table shows how to calculate required storage for the extract area
necessary for the extract string in the figure shown for the EXTSTRLN parameter:
28
UICB Field
Data Definitions
Storage
UITMPDDN
Character length of 8
8 bytes
UIRTNCD
Fullword
4 bytes
UIPROC#
Fullword
4 bytes
UIMSGID
Character length of 8
8 bytes
UICB Fields
The following table shows the valid UICB fields. Specifying these fields in the
EXTSTRLN parameter results in feedback in the extract area, defined by the
EXTAREA parameter. Exact definitions are in the DGA$UICB macro found in
$CD.SDGAMAC. In the table, the Control Block Builder Syntax Error Work Areas
have a value only when appropriate. For the Boolean Flags, output is Y (bit is on)
or N (bit is off).
Name
Type
LN
Description
UIRCBLNG
halfword
The length of the control block
UIDESCR
character
16
UICB identifier
UITCA
address constant
Task Control Area
UIBRCB
address constant
Batch Region Control Block
UIDYNCB
address constant
Dynamic Allocation Control Block
UITPCB
address constant
Text Parser Control Block
UILEVEL
fullword
Modal level counter
UITMPDCB
address constant
Temporary file DCB
UIMSGCB
address constant
Message Control Block
UIUNODE
character
16
User node ID
UIUID
character
64
User ID
UIPSWD
character
64
Signon password
UINPSWD
character
64
New Signon password
UITMPVOL
character
Volume serial number of temporary file if not specified by

user
UNTMPDDN
character
DDNAME used for temporary DSN
UIUSRTYP
character
User Type (operator, administrator, user)
UIAPPLID
character
VTAM logon ID
UIRTNCD
fullword
API return code
UIMSGID
character
API message ID
UILNODE
character
16
Name of node that is "local" to DTF
UILPP
halfword
Lines per page for printed output
UITMPLNG
halfword
Length of TSO temporary file name
UITMPDSN
character
44
TSO temporary file name
UIPUBLNG
halfword
Length of Process Library name
UIPUBDSN
character
44
Process Library name
UIMSGLNG
halfword
Length of message library name
UIMSGDSN
character
44
Message library name
UINETMAP
character
64
Network map file name
UIPROC#
fullword
Process number from submit
UIDSPLY
address constant
Address of SCDSPLY
UISTRING
address constant
Address of SCSTRING
****************
************
UILABL#
halfword
Length of Sterling Connect:Direct label
UILABL
character
Sterling Connect:Direct label
Start of control block builder syntax error work area
29
Name
Type
LN
Description
UICMD1#
halfword
Length of first word in Sterling Connect:Direct command
UICMD1
character
First word in Sterling Connect:Direct command
UICMD2#
halfword
Length of second word in Sterling Connect:Direct

command
UICMD2
character
Second word in Sterling Connect:Direct command
UIKLST#
halfword
Length of keyword that starts a list
UIKLST
character
Keyword that starts a list
UIKEYW#
fullword
Length of keyword in list before error
UIKEYW
character
Last keyword in list before an error
UIPARM#
halfword
Length of parameter associated with UIKEYW
UIPARM
character
Parameter in error associated with UIKEYW
UIERRM1#
halfword
Length of UIERRM1 string
UIERRM1
character
64
All of the above work areas resolved into a string
UIERRM2
character
64
Msg ID and text for parsing error
****************
************
UIERRON
character
Indicates message in UIERRM1
UIERRLAB
character
Indicates something in UILABL
UIERRCM1
character
Indicates something in UICMD1
UIERRCM2
character
Indicates something in UICMD2
UIERRSCP
character
Indicates parsing error
UIERRC1O
character
Indicates open delimiter after command keyword, for

example, "IF ("
UIERRC2O
character
Indicates open delimiter after second command keyword
UIERRG
character
Indicates VTAM error msg in UIERRM1
UIERRLST
character
Indicates something in UIKLST
UIERRLOP
character
Indicates open delimiter after UIKLST
UIERRLCL
character
Indicates close delimiter after UIKLST
UIERRLEQ
character
Indicates equal sign after UIKLST
UIERRLCM
character
Indicates comma after UIKLST
UIERRLSP
character
Indicates space after UIKLST
UIERRKEY
character
Indicates something in UIKEYW
UIERRKOP
character
Indicates open delimiter after UIKEYW
UIERRKCL
character
Indicates close delimiter after UIKEYW
UIERRKEQ
character
Indicates equal sign after UIKEYW
UIERRKCM
character
Indicates comma after UIKEYW
UIERRKSP
character
Indicates space after UIKEYW
UIERRBPC
character
Indicates close delimiter before a parameter in a list
UIERRPRM
character
Indicates something in UIPARM
UIERRPOP
character
Indicates open delimiter after UIPARM
UIERRPCL
character
Indicates close delimiter after UIPARM
UIERRPEQ
character
Indicates equal sign after UIPARM
30
Start of boolean flags
Name
Type
LN
Description
UIERRPCM
character
Indicates comma after UIPARM
UIERRPSP
character
Indicates space after UIPARM
UIF1SUBM
character
Indicates a submitted Process
UIGOTDSN
character
Indicates found temporary file name as Signon command

parameter
UITFILE
character
Indicates data is generated into temporary file
UIEOF
character
Indicates reached EOF of Process file
UIMODAL
character
Indicates modal statement processed
UITFILEX
character
Reserved
UIMASTER
character
Indicates this UICB is master
UIRECON
character
Indicates a reconnect attempted
UIINACT
character
Indicates VTAM session for this UICB failed
UILOCAL
character
Indicates local node session
UIESF
character
Indicates ESF=YES on Signon command
UIZOPSWD
character
Indicates blank password on Signon
UIZNPSWD
character
Indicates blank new password on Signon
****************
************
UIRAT@
address constant
PTR to resource address table
UIDRLSE#
halfword
DTF release level
UIDPUF#
halfword
DTF PUF level
UIDPUT#
halfword
PUT tape number
UILINE#
halfword
Line number within Process in error
UIRLSE#
halfword
Current release, version and mod level
UIPUF#
halfword
Current PUF level
UI@MASTR
address constant
Master (user) UICB
UI@ACTIV
address constant
Currently active UICB
UI@FPTR
address constant
Next UICB
UI@BPTR
address constant
Previous UICB
UIALOTYP
character
Allocation type for temporary file
UIALOPRI
character
Allocation of prime space for temporary file
UIALOSEC
character
Allocation of secondary space for temporary file
UIALOUNI
character
Allocation unit for temporary file
UIALOVOL
character
Allocation of volume serial number for temporary file
UIFOLD
character
Fold to upper case if YES UIPRTALC
UIPRTALC
character
80
User-defined Sterling Connect:Direct print destination
UIPACCT#
halfword
Length of PNODE accounting data
UIPACCT
character
255
PNODE accounting data text
UISACCT#
halfword
Length of SNODE accounting data
UISACCT
character
255
SNODE accounting data text
UIGSCAPI (VM)
character
GCS API virtual machine identifier
END OF BOOLEAN FLAGS
31
DGADCHLA Return Codes

Return codes reflect the status of the DGADCHLA communications with the API.
These codes only reflect whether DGADCHLA could process the request and pass
the command to the DTF. They do not reflect the completion status of the
command.
The following table defines each return code.
RC
Description
00000000
The command executed normally.
00000004
Signon to the master session failed, but the ESF environment is

established.
00000008
A non-ESF command attempted in an ESF environment.
0000000C
A session is lost in a multiple session environment.
00000010
The master session is lost.
00000014
The master session signed off successfully.
00000018
The master session signon failed, and no ESF ability exists.
0000001C
A non-master signon failed.
00000020
DGADCHLA received an invalid number of input parameters.
00000024
The output specifications included an invalid parameter.
00000028
An invalid pointer to the UICB is passed to DGADCHLA.
For more information on master sessions and multiple session environments, refer
to Signing On to Sterling Connect:Direct for z/OS.
Extract Fields for DGADCHLA Return Codes

The following extract fields apply to DGADCHLA return codes:
Field
Description
UIRTNCD
Lists return codes. UIRTNCD is set on completion of every command

processed by the DTF.
UIMSGID
Lists message IDs. UIMSGID is set on completion of every command

processed by the DTF.
UIPROC#
Identifies Process numbers. UIPROC# is set for every successful Submit

command.
See UICB Fields for the complete list of UICB fields.
DGADCHLA Examples
The following examples show how required and optional parameters appear in
sample programs. There is also a sample job stream for executing the program.
Required Parameters and Calling Sequences

The following example shows how the required parameters and calling sequences
appear in a sample Assembler program:
32
******************************************************************
*
THE DATA DEFINITIONS ARE AS FOLLOWS:
*
******************************************************************
CMDLEN
DS
H
LENGTH OF COMMAND STRING
CMD
DS
CL4096
COMMAND STRING
UICB@
DS
A
POINTER TO UICB
OUTSPECS
DC
CYYSLYNN
OUTPUT SPECIFICATIONS
******************************************************************
*
*
*
THE DGADCHLA INVOCATION WOULD BE:
*
*
*
******************************************************************
CALL DGADCHLA,(CMDLEN,UICB@,OUTSPECS),VL
The following example shows how the required parameters and calling sequences
appear in a sample PL/I program:
******************************************************************
*
THE DATA DECLARATIONS ARE AS FOLLOWS:
*
******************************************************************
DECLARE
CMD_PARM
FIXED BINARY (31) BASED (R),
UICB_PARM
FIXED BINARY (31) INITI (0B),
OUTSPEC_PARM
CHAR (7) INIT (YYSLYNN),
CMD
CHAR (4096) VARYING,
R
POINTER;
******************************************************************
*
*
*
THE DGADCHLA INVOCATION WOULD BE:
*
*
*
******************************************************************
R=ADDR(CMD) ;
CALL DGADCHLA(CMD_PARM, UICB_PARM, OUTSPEC_PARM);
Optional Parameters
The following example shows how the optional parameters look in a sample
Assembler program:
33
*********************************************************************
**
THE PARAMETERS WOULD BE DEFINED AS FOLLOWS:
**
*********************************************************************
CMDLEN
DS
H
CMD
DS
CL4096
UICB@
DS
A
OUTSPECS DC
CYYSLYYY
EXTSTRLN DC
H32
EXTSTR
DC
C'UITMPDDN UIESF UIPROC# UIMSGID
EXTAREA
DS
OCL24
/*OUTPUT FROM THE UICB EXTRACT
EXTMPDDN DS
CL8
/*VALUE OF UITMPDDN
EXESF
DS
F
/*VALUE OF UIRTNCD
EXPROC#
DS
XL4
/*VALUE OF UIPROC#
EXMSGID
DS
CL8
/*VALUE OF UIMSGID
EXTRC
DS
F
EXTMSG
DS
CL8
INVALKEY DS
CL8
**********************************************************************
**
NOTE THAT THE EXTRACT STRING ITSELF IS 30 BYTES LONG,
*
**
BUT THE DUMP OF ITS EXTRACT WILL USE 31 BYTES.
*
**
*
**
INSIDE THE MAIN BODY OF THE PROGRAM, THE CALL TO
*
**
DGADCHLA WOULD LOOK LIKE:
*
**
*
**********************************************************************
CALL DGADCHLA,(CMDLEN,UICB@,OUTSPECS,EXTSTRLN,EXTAREA,
*
EXTRC,EXTMSG,INVALKEY),VL
*/
*/
*/
*/
*/
Sample Job Stream for Executing the Program

The following example shows a sample job stream that executes a Sterling
Connect:Direct program that invokes DGADCHLA.
//jobname JOB (ACCT),PGMR NAME,
//
NOTIFY=TSOUER,TIME=(1),
//
MSGCLASS=X,CLASS=A,PRTY=9,REGION=1024K
//JOBLIB
DD
DISP=SHR,DSN=$CD.SDGALINK
//CD
EXEC PGM=USERPROG
//DMPRINT
DD
SYSOUT=*
//DMNETMAP
DD
DISP=SHR,DSN=$CD.VSAM.NETMAP
//DMPUBLIB
DD
DISP=SHR,DSN=$CD.SDGAPROC
//DMMSGFIL
DD
DISP=SHR,DSN=$CD.VSAM.MESSAGE
//SYSUDUMP
DD
SYSOUT=*
//NDMCMDS
DD
SYSOUT=*
You must allocate several files using DD statements before executing a Sterling
Connect:Direct application program that calls DGADCHLA.
The following table defines the DD statements in the sample job stream:
34
Statement
Definition
DMPRINT
All output from SELECT PROCESS, SELECT STATISTICS, SELECT TYPE,

and SELECT USER commands is written to this DD. Also, output as a
result of the OUTSPECS specification is written to DMPRINT. DMPRINT
is optional, but often required.
DMNETMAP
This definition is the name of the network map file that contains the
names of all the nodes that Sterling Connect:Direct communicates with.
DMNETMAP is required if no NETMAP keyword is specified on the
SIGNON command.
Statement
Definition
DMPUBLIB
This definition is a library containing Processes. It is required.
DMMSGFIL
This definition is the name of the Message file. It is required.
NDMCMDS
If allocated, all command strings are written to the current file. It is

optional.
35
36
Chapter 5. Managing Sessions

Signing On to Sterling Connect:Direct for z/OS
The SIGNON command establishes your session with the DTF so that you can
issue commands.
You can control access to the Sterling Connect:Direct system through the Sterling
Connect:Direct Authorization Facility and security exits. For information on
security control, go to the IBM Sterling Connect:Direct for z/OS Administration Guide
and search for Implementing Security.
If you are using the Extended Submit Facility (ESF), you can submit the SIGNON
command even though the DTF is inactive.
Timeout Problems
If you are logged off involuntarily while using Sterling Connect:Direct via TCP/IP,
your problem may be related to the TCP/IP connection not being able to
communicate with the DTF. If you see the message TCP/IP SEND error;
Connection Lost, and press F1 to see the help for this message, the following text is
displayed for message SVTC006I:
MSGID ==> SVTC006I
MODULE ==> DMTSTSND
TCP/IP SEND error; Connection Lost
An error has been detected while sending a command via TCP/IP.
The TCP/IP connection has been lost. A possible cause is
Connect:Direct has been shutdown and all TCP/IP connections
have been closed.
System Action: Normal processing can not continue.
Response: Logoff and attempt to signon again.
Although the TCP/IP protocol does not have a mechanism to send you a console
message indicating that the client has been dropped and your session has timed
out, you can determine if this has happened to you by looking in the statistics file
for a signoff record with an SAFA019I error message that matches your user ID (be
sure to enter Y in the CHANGE EXTENDED OPTS field on the SELECT
STATISTICS panel and then enter SO as a record type on the next screen). For
more information, go to the IBM Sterling Connect:Direct for z/OS Administration
Guide and search for Signon and IUI/API Errors.
Sterling Connect:Direct provides an inactivity timer that is based on the number of
minutes a user can remain inactive without communicating with the DTF. An
administrator can specify this value using the TCP.API.TIMER global initialization
parameter. Sterling Connect:Direct will only recognize changes made to the
TIMEOUT parameter by an administrator. If you attempt to change this parameter
and you are not an administrator, you will not be able to sign on. You can
determine if this has happened to you by looking in the statistics file for a signon
record with an SAFA020I error message that matches your user ID. For more
information, go to the IBM Sterling Connect:Direct for z/OS Administration Guide and
search for Signon and IUI/API Errors.
37
Note: The rationale behind the timeout feature is to do housekeeping to keep the
number of hung sessions to a minimum and avoid the limit specifying the
maximum number of users that can be signed on to Sterling Connect:Direct.
Without the timeout feature, an administrator would have to recycle the DTF to
allow TCP/API logons to reconnect once the MAXUSER limit was reached.
Using SIGNON through the IUI

To execute the SIGNON command through the IUI, perform the following steps:
Procedure
1. Select Sterling Connect:Direct from your ISPF/PDF Primary Option Menu. The
Copyright and the Signon screen are displayed, unless SIGNON defaults are
previously set.
CMD ==>
VERSION
: 05
RELEASE
: 001
MODIFICATION
: 000
LEVEL
: 0000
TODAY IS
: 2011/02/24 (2011.055 )
THE TIME IS: 09:01
More:
USER ID => USER01
PASSWORD =>
NEW PASS =>
NODE NAME =>
TRANSPORT =>
COMMUNICATION ADDRESS =>(
,
DESCRIPTION =>
TIMEOUT =>
Licensed Materials - Property of IBM
5655-X01 Copyright IBM Corp. 2011
All Rights Reserved
.
IBM is a Trademark of International Business Machines
The Signon screen indicates the version, release, modification, and Program
Update Tape (PUT) levels of Sterling Connect:Direct.
2. Type your user ID and press Enter.
Depending upon your site configuration, you may also need to type in a
password, a new password, node name, transport, communications address,
and case sensitivity option before pressing Enter. These parameters are
described in SIGNON Command on page 40, or press PF1 for Help.
If you are using the Extended Submit Facility (ESF), the DTF does not need to
be active to execute the SIGNON, SIGNOFF, and SUBMIT commands.
Note: If the Error requesting session, Sterling Connect:Direct may be inactive
message is displayed, the Sterling Connect:Direct DTF is not started.
Results
If your signon is successful, the Primary Options Menu is displayed, unless you
have updated your SIGNON defaults to execute an initial command.
Viewing Your Current Signon Parameters

You can view your signon default parameter settings.
38
Procedure
To see how your signon parameters defaults are currently set, select the WHO
option from the Primary Options Menu. The following figure shows an example of
the User Information display produced by the WHO option.
Connect:Direct IUI USER INFORMATION
CMD ==>
USER ID==> USER01
USER NODE
==> node.name
TRANSPORT PROTOCOL
==> NETMAP
COMMUNICATION ADDRESS ==> APPLID
TEMPORARY DSN DDNAME ==> TMPDD
TEMPORARY DSN VOLSER ==> TMPVSER
DATA SETS:
TEMPORARY DSN
==> CD.TEMP.DSN
MESSAGE DSN
==> CD.MSG.VER01
NETWORK MAP DSN
==> CD.NETMAP.VER01
PUBLIC PROCESS DSN
==> CD.PUBLIB
IUI VERSION
==> VV
IUI RELEASE
==> RRR
IUI MODIFICATION
==> MMM
IUI PUT LEVEL
==> PPPP
hh:mm
Setting Up Signon Defaults

Use the Signon Defaults screen to set up signon default information.
Procedure
Select SD from the Primary Options Menu to access the Signon Defaults screen.
node.name
SIGNON DEFAULTS
hh:mm
CMD==>
CURRENT DEFAULTS:
USER ID ==>
PASSWORD ==>
TRANSPORT==>
COMMUNICATION ADDRESS ==>(
,
DESCRIPTION ==>
TIMEOUT
==> YES
TEMPORARY DATA SET NAME ==>
ALLOCATION TYPE
==>
PRIMARY SPACE
==>
UNIT TYPE ==>
SECONDARY SPACE
==>
VOL=SER
==>
EXTENDED SUBMIT FEATURE ==>
UPPER CASE FOR PRINT
==>
PRINT FILE DESTINATION ==>
PNODE ACCOUNTING DATA
==>
SNODE ACCOUNTING DATA
==>
DO YOU WANT ALL COMMANDS FOR THIS SESSION TO BE CASE SENSITIVE? ==> NO
INITIAL COMMAND
==>
Note: Instead of users individually altering their signon defaults, the Sterling
Connect:Direct administrator can define global signon defaults. With this method,
users will not be responsible for increasing their allocation and can also avoid SB37
ABENDs. For more information, refer to Global Signon Defaults in the IBM Sterling
Connect:Direct for z/OS Administration Guide.
The INITIAL COMMAND field enables you to bypass the Primary Options Menu
and have a designated command screen display automatically at signon. For
example, to have the User Information screen (WHO) display automatically at
39
signon, type WHO in the Initial Command field.

Command stacking is allowed. For example, type ADMIN.ST in the INITIAL
COMMAND field to branch to the View Type Record (ST) option of the
Administration Menu (ADMIN).
By typing your user ID and other information in the SIGNON Defaults panel, you
can bypass the SIGNON panel.
SIGNON Command
The SIGNON command has the following format and associated parameters. The
required parameters and keywords are in bold print. Default values for parameters
and subparameters are underlined.
Label
Command
Parameters
(optional)
SIGNON
NETMAP = network map data set name

CASE= Yes | No
COMADDR= (Port number, IP address |
alias name)
ESF= Yes | No
FOLD= Yes | No
NODE= node name
PACCT= 'pnode accounting data'
PRINT= destination of printed output
RECONNECT
SACCT= 'snode accounting data'
SPACE= (CYL | TRK | blk,([prim],[sec]))
TMPDD= preallocated data set ddname
TMPDSN= preallocated data set name
TRANSPORT= SNA | TCP | NETmap
UNIT= temporary dsn unit type
USERID= (ID, pswd, newpswd)
VOLSER= volume serial
DESCRIPTION= '30-character string'
TIMEOUT= Yes | No
40
Parameter Value
Description
NETMAP = network Specifies the network map data set name, which is a 1-44
map data set name
alphanumeric character string with the first character alphabetic.
This parameter is required. Ask your administrator for information
about completing this value.
If you provide the DMNETMAP DD name in the job stream used
with DMBATCH, you are not required to include this parameter
with the SIGNON command. If you specify the data set name in
both places, the network map data set name you specify on the
SIGNON command takes precedence.
For the IUI, the network map data set name is specified in the
ISPF/PDF Primary Option Menu as a parameter of the DMISTART
program. This data set name is established by your IBM Sterling
Connect:Direct administrator at installation and is not indicated
through the IUI SIGNON command screens.
CASE= Yes | No
The CASE parameter determines case sensitivity. It specifies whether

parameters associated with accounting data, user ID, password, and
data set name in the commands which follow the signon must be
case sensitive. The default is No. This parameter is optional.
You can override this designation on a command-by-command basis
by adjusting the case sensitivity parameter on the individual
command.
COMADDR= (Port
number, IP address
| alias name)
Specifies the communications address used in TCP/IP connections to

the DTF. This parameter is specified only if the TRANSPORT
parameter is set to TCP.
The port number specifies the port number used for TCP/IP
communications. This value is the value from the TCP.API.LISTEN
initialization parameter of the DTF that you want to sign on to.
The IP address/alias name specifies the IP address or alias name
used for TCP/IP communications.
If you use the COMADDR parameter, you must specify both the
port number and IP address/alias name.
If you use alias name or long domain name resolution, you do not
need to supply the IP address in the COMADDR parameter or in
the COMMUNICATIONS ADDRESS field during Sterling
Connect:Direct SIGNON. The name resolution feature resolves a
valid alias name or long domain name to the matching IP address.
The maximum length of the IP address|alias name variable is 16
characters. If you want to use an LDNS (long domain name system)
or an alias name greater than 16 characters, the name must be
defined in the network map, and the TRANSPORT must be coded as
NET.
Note: Allocate the SYSTCPD DD to the TCPDATA file in both the
Sterling Connect:Direct startup JCL and API session startup JCL
when you request domain name resolution.
41
Parameter Value
Description
ESF= Yes | No
Specifies whether the Extended Submit Facility (ESF) is available for

the current signon. This parameter is optional. The default value is
Yes.
The ESF enables you to submit Processes even if the DTF is not
active. When signing on to a Sterling Connect:Direct DTF that is
active, but with no VTAM APPLID available, the ESF enables signon
to the DTF. When you submit the Process it is enabled and placed in
the TCQ as soon as the ESF.WAIT time expires.
ESF is available only for Processes submitted on the local node. You
can only issue the Sterling Connect:Direct SIGNON, SUBMIT, and
SIGNOFF commands using the ESF; all other Sterling Connect:Direct
commands are rejected.
CAUTION:
If you use the MAXDELAY PROCESS statement keyword, the
message SCBI221I MAXDELAY not supported for ESF submits, is
displayed when the DTF is down and the Process will not submit.
FOLD= Yes | No
Determines printing upper case control. It specifies whether printed

output, an option of the various SELECT commands, are all
uppercase letters. The default value is No, specifying printed output
of uppercase and lowercase letters. This parameter is optional.
NODE= node name
Specifies the name of the node (DTF) you sign on to. It is the name
assigned to a node defined in the network map definitions. This
parameter is optional.
PACCT= 'pnode
accounting data'
Specifies the accounting data for the primary node (PNODE). The
maximum length of the accounting data is 256 characters. If special
characters, such as a space, are part of the accounting data, you
must enclose the string in single quotation marks. Sterling
Connect:Direct uses this data as a default for each Process unless
you override it on the SUBMIT command, PROCESS statement, or
SUBMIT statement. This parameter is optional.
PRINT= destination
of printed output
Specifies an allocation string that determines the destination of the

printed output that you request on the various SELECT commands.
This parameter is optional. SYSOUT=A is the default value. An
example follows.SYSOUT=C DEST=RMT1 FREE=CLOSE RETURN=(DD)
You must include both FREE=CLOSE and RETURN=(DD) in the string for
this specification. When using the IUI, if you do not specify a
destination, Sterling Connect:Direct routes the output to the SYSOUT
class specified in the initialization parameters (external to Sterling
Connect:Direct) under the TSO user ID. If you modify the
destination, you need to sign off Sterling Connect:Direct after
updating the field in order for the new destination to be in effect.
42
RECONNECT
Specifies that you can reestablish your VTAM session without

having to sign off and sign on again. You can lose a VTAM session
due to a link or line failure. This parameter is optional. The USERID
parameter is the only other parameter that you specify with the
RECONNECT option.
SACCT= 'snode
accounting data'
Specifies the accounting data for the secondary node (SNODE). This
parameter is optional. The maximum length of the accounting data
is 256 characters. If special characters, such as a space, are part of
the accounting data, you must enclose the string in single quotation
marks. Sterling Connect:Direct uses this data as a default for each
Process unless you override it on the SUBMIT command, PROCESS
statement, or SUBMIT statement.
Parameter Value
Description
SPACE= (CYL |
TRK |
blk,([prim],[sec]))
Specifies the temporary data set (TMPDSN) allocation type, primary

space allocation, and secondary space allocation. This parameter is
optional.
The first subparameter is the allocation type. An allocation type of
CYL specifies space allocation by cylinder. CYL is the default value.
An allocation type of TRK specifies space allocation by track. An
allocation type of blk specifies space allocation by the average block
length of the data. Sterling Connect:Direct computes the number of
tracks to allocate.
The second subparameter, prim, specifies the primary allocation of
storage. The default value is 1.
The third subparameter, sec, specifies the secondary allocation of
storage. The default value is 1.
TMPDD=
Specifies the ddname of a user-supplied preallocated data set. The
preallocated data set maximum length is an 8-character alphanumeric string. This
ddname
parameter is optional. Do not use both the TMPDD and TMPDSN
parameters at the same time in the SIGNON command.
Specifies the name of a preallocated data set used to receive
TMPDSN=
preallocated data set command results that are printed or displayed. The data set name is
name
a 1-44 alphanumeric character string that must conform to z/OS
standards for data set names. This parameter is optional, and when
not specified, Sterling Connect:Direct builds a system temporary
data set. It normally derives the name for the data set based on your
TSO ID. In some cases, this derived data set name violates your
facility naming convention. Use the Signon Defaults screen to
override the data set name as needed.
If you name a data set at signon time, preallocate it with the
following attributes prior to signing on to Sterling Connect:Direct
(4104 is the minimum BLKSIZE):
DSORG=PS LRECL=4100 RECFM=VBA BLKSIZE=4104
Do not use both the TMPDD and TMPDSN parameters at the same
time in the SIGNON command.
TRANSPORT= SNA
| TCP | NETmap
Defines the communications protocol to use for the session. This

The default value (NETmap) indicates that the protocol defined in
the network map is used for the session.
A value of SNA tells Sterling Connect:Direct to establish the session
using SNA. You must define the node you are signing on to as an
SNA node, or the SIGNON Process fails.
A value of TCP tells Sterling Connect:Direct to establish a TCP/IP
session. Sterling Connect:Direct uses the communications address
specified in the COMADDR parameter (see page 62 for a description
of the COMADDR parameter), if that parameter is specified as part
of the SIGNON command. If the COMADDR parameter is not
specified, Sterling Connect:Direct tries to establish the session using
the communications address from the network map. If an invalid
COMADDR parameter is supplied, Sterling Connect:Direct
establishes an ESF API session.
43
Parameter Value
Description
UNIT= temporary
dsn unit type
Specifies the temporary data set name (TMPDSN) unit type, which
must be a 1-8 alphanumeric character string defining the unit type
for data set allocation. This parameter is optional. If omitted, the
operating system defined default for DASD is used by dynamic
allocation.
USERID= (ID, pswd, Specifies your signon security information. This parameter is
newpswd)
optional.
ID specifies the security ID that Sterling Connect:Direct passes to a
security exit. It can contain 1-64 characters of any kind, and is
case-sensitive.
pswd specifies the current security password. The security exit uses
this parameter to validate the current security password. It contains
1-64 alphanumeric characters, and is case-sensitive.
newpswd specifies the new security password. The security exit uses
this parameter to change the current security password to the new
security password. It contains 1-64 alphanumeric characters, and is
case-sensitive.
When you attempt a sign on to a remote node, the user ID and
password information must correspond to security procedures at
that remote node.
VOLSER= volume
serial
Specifies the temporary data set name (TMPDSN) volume serial

number, which must be a 1-8 character alphanumeric string defining
the volume serial number for data set allocation. This parameter is
optional.
DESCRIPTION=
'30-character string'
Describes the API type that is logging on. It is displayed with the
Select Task command. If Sterling Connect:Direct cannot determine
the API type, the communication address is used.
Defaults: DMCHLAPI, DMBATCH, ISPFIUI, CONSOLEUI, ICOUI,
CICSUI, and Java Application Interface
TIMEOUT= Yes |
No
Specifies whether the value specified for the TCP.API.TIMER global

initialization parameter applies to this specific user. This parameter
is optional. The system will only accept changes to this field made
by an administrator and only for their own IUI session; all others
will be governed by the initialization parameter. The default value is
Yes. Do not use the TIMEOUT keyword in DMBATCH.
Using SIGNON through the Batch Interface

About this task
To use the SIGNON command from the batch interface, perform the following
steps:
Procedure
1. Place the command in the DGADBATC job stream as described in Sample Job
Stream to Run the Batch Interface.
2. Submit the job while is running. If you are using the Extended Submit Facility
(ESF), the DTF does not need to be active for the SIGNON command to
process. The following example shows a SIGNON command in which the user
44
specifies a pre-allocated temporary data set named MYUID1.TEMP.DSN which

resides on SYSDA. The accounting data is specified for the PNODE and
SNODE.
SIGNON
NETMAP=DALLAS.NETMAP USERID=(MYUID1,MYPSWD) PACCT=JOB FOR SYSMAINT, DEPT.27, MARKETING SACCT=JOB FOR INVENTRY, DEPT.55, ACCOUNTING TMPDSN=MYUID1.TEMP.DSN UNIT=SYSDA
See Signing On to Sterling Connect:Direct for z/OS for additional examples of

the SIGNON command in the batch interface.
Signing On to the API

The communication address used to establish a connection to Sterling
Connect:Direct is determined by the TRANSPORT parameter defined in the
SIGNON command. The default for the TRANSPORT parameter is NET
(NETMAP) which means that the protocol defined in the NETMAP Adjacent node
entry is used. For more information, see Adjacent Node Definition Examples.
Parameter Value
Description
TRANSPORT = NET Default. When TRANSPORT is defined as NET, the sign on process
retrieves the Adjacent node entry to determine if the TCPAPI
parameter has been defined. If TCPAPI exists, then a TCP connection
is attempted using the communication address defined. The
communication port number is obtained from the TCPAPI
parameter, and if the IP address exists in the TCPAPI parameter, it is
also used. If the IP address does not exist in the TCPAPI parameter,
it must be obtained from either the Adjacent node or the LDNS
parameter. If the TCPAPI does not exist, the APPLID parameter is
retrieved and SNA is used as the protocol.
TRANSPORT = SNA When TRANSPORT is defined as SNA, the sign on process retrieves
the Adjacent node entry to determine the APPLID parameter, and
SNA is used as the protocol. If the APPLID parameter does not exist,
then an ESF SIGNON is performed.
TRANSPORT = TCP When the TRANSPORT is defined as TCP, the communication
address must be specified on the SIGNON command. For more
information, go to the IBM Sterling Connect:Direct for z/OS
Administration Guide and search for Initializing Sterling
Connect:Direct without SNA Support.
Adjacent Node Definition Examples

To only allow SNA API signons:
/* PNODE=SNODE WITH SNA API SIGNON ONLY */
ADJACENT.NODE=(( CD.OS390.NODE,M1DEV93C) PARSESS=(53 2) APPLIDS=(M1CDI701 M1CDI702 M1CDI703) )
To only allow TCP API signons using an IPv4 address:

/* PNODE=SNODE WITH TCP API SIGNON ONLY USING IP ADDRESS */
ADJACENT.NODE=(( CD.OS390.NODE,M1DEV93C) PARSESS=(53 2) TCPAPI=(4198,111.222.333.444) )
45
To only allow TCP API signons using an IPv6 address:

/* PNODE=SNODE WITH TCP API SIGNON ONLY USING IP ADDRESS */
ADJACENT.NODE=(( CD.OS390.NODE,M1DEV93C) PARSESS=(53 2) TCPAPI=(4198,1111:2222:3333:4444:5555:6666:7777:8888) )
To only allow TCP API signons using the LDNS parameter:

/* PNODE=SNODE WITH TCP API SIGONON ONLY USING LDNS */
ADJACENT.NODE=(( CD.OS390.NODE,M1DEV93C) PARSESS=(53 2) TCPAPI=(4198,) LDNS=long.domain.name )
To allow both SNA and TCP API signons:

/* PNODE=SNODE WITH BOTH SNA AND TCP API SIGNON */
ADJACENT.NODE=(( CD.OS390.NODE,M1DEV93C) PARSESS=(53 2) TCPAPI=(4198,111.222.333.444) APPLIDS=(M1CDI701 M1CDI702 M1CDI703) )
or
/* PNODE=SNODE WITH BOTH SNA AND TCP API SIGNON */
ADJACENT.NODE=(( CD.OS390.NODE,M1DEV93C) PARSESS=(53 2) TCPAPI=(4198,) LDNS=long.domain.name APPLIDS=(M1CDI701 M1CDI702 M1CDI703) )
Signing On to Multiple Sessions

Use the SIGNON command to sign on simultaneously to multiple sessions of the
DTF. The SIGNON command parameters which are valid for the multiple session
signon are a subset of the full SIGNON command parameters. For more
information, see Using SIGNON through the Batch Interface.
Master Session
The first successful SIGNON command establishes the master session. The master
session is the active session until another session is established. Each subsequent
signon becomes the active session unless sessions are swapped using the SWAP
NODE command.
Signing on to the master session and signing on to another node under the master
session requires two different signons. The parameters specified for the master
session signon dictate the environment for all sessions running under the master
session.
Non-Master Session
For a session other than master, you are limited to the following SIGNON
command parameters.
Label
Command
Parameters
(optional)
SIGNON
NODE= node name

RECONNECT
46
Label
Command
Parameters
USERID= (ID, pswd, newpswd)
See Using SIGNON through the Batch Interface for descriptions of these
parameters.
SIGNOFF Sequence
Carefully control your SIGNOFF command sequence because if you sign off the
master session, Sterling Connect:Direct signs off all other sessions. If you sign off a
non-master session, Sterling Connect:Direct only signs off that session, and the
master session immediately becomes the active session again, regardless of the
order in which the sessions are established. See Sequencing the SIGNON, SWAP
NODE, and SIGNOFF Commands for examples of the importance of the sequence
of your SIGNOFF commands.
Switching Nodes
When you issue multiple signons, one node can perform one function and another
node a different function. The SWAP NODE command enables you to swap from
node to node. See Using SWAP NODE through the Batch Interface for the SWAP
NODE command description and examples.
Using the Batch Interface for Multiple Session SIGNON

To use the multiple session SIGNON command through the batch interface, place
your commands in the DGADBATC job stream and submit the job while Sterling
Connect:Direct is running. If you have the Extended Submit Facility (ESF)
available, the DTF does not need to be running to submit the job.
See the examples in Sequencing the SIGNON, SWAP NODE, and SIGNOFF
Commands for job streams that issue SIGNON, SWAP NODE, and SIGNOFF
commands and an explanation of the significance of the command sequence in the
job stream.
Using the IUI Multiple Session SIGNON Command

To access the Multiple Session Signon screen, select MS from the Primary Options
Menu.
node.name
CMD ==>
hh:mm
yyyy.mm.dd
yyyy.ddd
MULTIPLE SESSION SIGNON

USER ID
==> USER01
PASSWORD ==>
NEW PASS ==>
NODE NAME ==>
TRANSPORT ==> NET
COMMUNICATION ADDRESS ==>(
,
DESCRIPTION ==>
RECONNECT ==> N (Y OR N. TO THE *ACTIVE* NODE
AFTER A SESSION FAILURE)
PNODE ACCOUNTING DATA
==>
SNODE ACCOUNTING DATA
==>
DO YOU WANT ALL COMMANDS FOR THIS SESSION TO BE CASE SENSITIVE? ==> NO
The Multiple Session Signon screen enables you to sign on to more than one node
during a single ISPF/PDF session. The APPLIDS value in the network map
47
Adjacent Node definition determines the maximum number of sessions that

Sterling Connect:Direct is allowed on one DTF. Each signon uses an additional
VTAM APPLID.
See SIGNON Command on page 40 for field descriptions, or press the PF1 key
for Help.
Swap Node Command

The SWAP NODE command enables you to swap to another node when you are
signed on to more than one node at a time. Use the SWAP NODE command to
specify which node a command is issued to.
The SWAP NODE command has the following format and associated parameter:
Label
Command
Parameters
(optional)
SWAP NODE
node name
The only parameter for the SWAP NODE command is node name, which specifies
which node to swap to in a multiple session environment. The node name is the
name assigned to the LOCAL.NODE field defined in the network map definitions.
Using SWAP NODE through the IUI

You can use the Swap/Display User Sessions screen to swap to another node or
delete (signoff) another node.
Procedure
1. Select option SW from the Primary Options Menu to access the
SWAP/DISPLAY User Sessions screen. The screen displays all user sessions for
this ISPF/PDF session.
----------------------SWAP/DISPLAY USER SESSIONS------- Row 1 to 2 of 2
==>
SCROLL ===> PAGE
NODE
COMMUNICATION ID
CURRENT
STATUS
USERID
---------------------------------------------------------------------node.name1
applid0
*ACTIVE*
*MASTER* **LOCAL*
userid2
node.name3
applid1
userid1
****************************** Bottom of data *************************

v To swap sessions, type S in the input field to the left of the node name and
press Enter. ACTIVE is displayed next to the node name you just selected. To
determine which node is currently signed on when this field is not
displayed, look to the upper left corner of most panels for the display of the
node name.
v To delete or sign off a session, type D in the input field to the left of the
node name and press Enter.
Note: If you sign off the master session, the first node you signed on, all
sessions are lost.
48
Using SWAP NODE through the Batch Interface

To use the SWAP NODE command from the batch interface:
Procedure
1. Place your commands in the DGADBATC job stream as described in Sample
Job Stream to Run the Batch Interface.
2. Submit the job while Sterling Connect:Direct is running.
3. Verify your results.
For example, the following command swaps you from your current active
remote node with a user ID of JONES2 to the local node under the user ID of
JONES1:
//SYSIN
SIGNON
DD *
USERID = (JONES1) NODE = CD.LOCAL
SIGNON USERID = (JONES2) NODE = CD.REMOTE
SWAP
NODE CD.LOCAL
SELECT NETMAP WHERE(NODE=CD.LOCAL)
SIGNOFF
SIGNOFF
/*
Sign Off Command

The SIGNOFF command terminates a connection to the DTF. If you are using the
Extended Submit Facility (ESF), you can submit the SIGNOFF command even
though the DTF is inactive.
The SIGNOFF command has the following format. No associated parameters are
available.
Label
Command
(optional)
SIGNOFF
Parameters
Using SIGNOFF Through the IUI

The following table identifies how to SIGNOFF from various locations of the IUI.
You must press Enter after each SIGNOFF command.
SIGNOFF Command
Location
SIGNOFF
SIGNON screen or the Primary Options Menu
End
=SIGNOFF or =X
Command Line
When you sign off Sterling Connect:Direct, the system returns you to the ISPF
menu.
Follow these rules when you sign off Sterling Connect:Direct:
v You must type a SIGNOFF command twice from the command line.
49
Note: The first SIGNOFF command returns you to the Primary Options menu and
the second SIGNOFF command returns you to the ISPF menu.
v You only need to sign off once from the SIGNON screen or the Primary Options
Menu.
Using SIGNOFF through the Batch Interface

To use the SIGNOFF command from the batch interface, perform the following
steps:
Procedure
1. Place your commands in the DGADBATC job stream as described in Sample
job stream to run the batch interface on page 10.
2. Submit the job while Sterling Connect:Direct is running. If you have the
Extended Submit Facility (ESF) available, the DTF does not need to be running
in order for the SIGNOFF command to function.
The following example shows a SIGNON command followed by a SIGNOFF
command.
SIGNON
SIGNOFF
USERID=(MYUID1,MYPSWD) NETMAP=NETMAP.NAME
See the examples in Sequencing the SIGNON, SWAP NODE, and SIGNOFF
Commands for more examples of the SIGNOFF command used with the
Multiple Session Signon feature and the SWAP command.
Sequencing the SIGNON, SWAP NODE, and SIGNOFF Commands

When you issue SIGNON, SWAP NODE, and SIGNOFF commands, the sequence
in which you issue these commands is important, as shown in the following
examples.
Example 1: Terminating Two Sessions with One SIGNOFF

Command
The following example shows a DGADBATC SIGNON to two different nodes and
the use of the SWAP NODE command. The SIGNOFF command in this example
causes Sterling Connect:Direct to terminate both sessions, because the active
session at signoff is the master session.
/* NETMAP = CD.NETMAP, BOSTON IS ACTIVE (MASTER) */
SIGNON
USERID=(SAM) NODE=CD.BOSTON
/* SIGN ON TO JERSEY */
SIGNON
USERID=(SAM) NODE=CD.JERSEY
/* SUBMIT COPY ON JERSEY */
SUB PROC=COPY1
/* SWAP TO BOSTON */
SWAP NODE CD.BOSTON
/* SUBMIT COPY ON BOSTON */
SUB PROC=COPY1
/* SIGN OFF BOTH NODES (terminating master session)*/
SIGNOFF
50
Example 2: Terminating a Master Session with the SIGNOFF

Command
In the following example, the first SIGNOFF command terminates the
CD.NEWYORK node because it is the last SIGNON command issued. The second
SIGNOFF command terminates both the CD.JERSEY and CD.BOSTON nodes
because the first SIGNOFF command made the master session the active session
and signing off the master session signs off all other sessions.
/* NETMAP = CD.NETMAP, BOSTON IS ACTIVE (MASTER */
SIGNON
SIGNON
/* SIGN ON TO NEWYORK */
SIGNON
USERID=(SAM) NODE=CD.NEWYORK
/* BOSTON IS ACTIVE AFTER SIGNOFF TO CD.NEWYORK */
SIGNOFF
/* SIGN OFF ALL SESSIONS (terminating master session) */
SIGNOFF
Example 3: Terminating a Non-Master Session with the SIGNOFF

Command
The following example illustrates that whenever a SIGNOFF command is issued to
a non-master session, the master session automatically becomes active again
regardless of the order in which the nodes are signed on.
If you try to swap to a node that is already active, the SWAP NODE command is
ignored. The USERID (or any other user ID specified) must be a user record in the
Sterling Connect:Direct authorization file or a valid ID for the security subsystem
in use, to sign on to the node.
/* NETMAP = CD.NETMAP, BOSTON IS ACTIVE (MASTER)
SIGNON
SIGNON
/* SIGN ON TO NEWYORK */
SIGNON
USERID=(SAM) NODE=CD.NEWYORK
/* NEWYORK ACTIVE */
SIGNOFF
SWAP NODE
CD.JERSEY
/* JERSEY ACTIVE */
SIGNOFF
/* SIGN OFF ALL SESSIONS */
SIGNOFF
*/
51
52
Chapter 6. Building, Modifying, and Submitting Processes

You can construct and submit Processes for execution in several ways, depending
upon the user interfaces available on your operating environment. These Sterling
Connect:Direct user interfaces include:
v
v
v
v
Interactive User Interface (IUI)

Sterling Connect:Direct Browser User Interface
IBM Sterling Connect:Direct File Agent
Batch interface
User-written programs issued through the Sterling Connect:Direct Application
Program Interface (API)
For more information about monitoring and manipulating your submitted

Processes, see Controlling Processes with Commands.
Note: The maximum size allowed for a Process is 1 MB.
You can also use the Sterling Connect:Direct Browser User Interface to perform
some Sterling Connect:Direct for z/OS procedures.
The following steps describe how a Process executes:
1. You submit a Process.
You create and submit a new Process or submit a predefined Process from a
Sterling Connect:Direct Process library.
2. The parser checks the syntax of the Process.
3. The Process is queued for execution and the submit message is issued
If the Process passes syntax checking, it is placed in a work queue based on
Process parameters, such as priority, class, and start time.
Sterling Connect:Direct work queues are referred to as the Transmission Control
Queue (TCQ) or the Process queue. A Process can have one of the following
queue states in the TCQ:
State
Description
EXECUTION Indicates that the Process is executing.

WAIT
Indicates that the Process is waiting until a connection is established or

available.
HOLD
Indicates that the Process is held on the queue until released by an operator
or the SNODE connects with a request for held work.
TIMER
Indicates that the Process is submitted to execute at the user-specified time

or date.
You can manipulate any Process in the TCQ with various Sterling
Connect:Direct commands that are described in the next chapter.
A message indicating that the Process submitted successfully is returned when
the Process is placed in the TCQ.
4. The Process is queued for execution and the submit message is issued.
You can manipulate any Process in the TCQ with various Sterling
Connect:Direct commands that are described in the next chapter.
53
A message indicating that the Process submitted successfully is returned when

the Process is placed in the TCQ.
5. Sterling Connect:Direct finds an available connection and Process execution
begins. The Process is selected for execution based on Process parameters and
the availability of the remote node.
Process Routing
The RETAIN, HOLD, and STARTT parameters route Processes as described in the
following table:
Parameters
Queue
Comments
None
Wait
Process remains on the Wait queue until Sterling

Connect:Direct can start a session with the SNODE at which
time it moves to the Execution queue.
RETAIN=INITIAL Hold
Process automatically executes each time Sterling

Connect:Direct is initialized with TCQ=WARM.
RETAIN=YES
Hold
A copy of the Process is kept in the Hold queue after it has

executed. The Process does not execute again until it is
released by a CHANGE PROCESS command.
HOLD=YES
Hold
Process remains in the Hold queue until someone releases

the Process.
HOLD=CALL
Hold
Process is automatically moved from the Hold queue to the

Wait queue when the SNODE contacts the node on which
the Process resides.
STARTT
Timer
When the scheduled time and date arrive, the Process is put
on the wait queue and is available for execution.
RETAIN=INITIAL is useful for Processes that contact other Sterling Connect:Direct

nodes each time Sterling Connect:Direct completes initialization. This action causes
any work queued on the remote node for the local node to begin. The DGAPHTBT
sample Process allows you to test if Sterling Connect:Direct is running on a
SNODE without actually running a Process on the node. For more information, go
to the IBM Sterling Connect:Direct for z/OS Administration Guide, search for
Maintaining the Network, and read the note on the DGAPHTBT Process.
You can use RETAIN=YES combined with STARTT to run a Process at a periodic
interval. For example, RETAIN=YES and STARTT=(Tuesday, 3pm) starts the
Process every Tuesday at 3 pm; RETAIN=YES and STARTT=(,12:00) starts the
Process each day at noon.
The Timer queue is also used for session retry and file allocation retry based on
Sterling Connect:Direct initialization parameters specified by a particular
installation. When retry limits are exhausted, the Process is moved to the Hold
queue with a WC (hold queue, waiting connection) status for session retry.
Note: For allocation failures to be requeued, you must set the REQUEUE
initialization parameter to YES so that the Process is placed in the HO RA (HO =
Held by Operator, RA = Held for Restart Due to Allocation Error) queue.
Process Queuing
When you submit a Process, Sterling Connect:Direct puts the Process in a logical
queue based on the Process statement routing parameters on Process Routing.
54
Sterling Connect:Direct selects Processes in a first-in first-out manner for execution

within Process class and priority as sessions are available. The following section
describes in detail how Sterling Connect:Direct selects Processes for execution.
Process Selection
Sterling Connect:Direct uses the parallel sessions capability of VTAM so that
multiple Processes can execute simultaneously between any two Sterling
Connect:Direct nodes. Process selection for each parallel session is based on a class
that the user specifies on a Process.
Note: Parallel sessions support requires you to specify PARSESS=YES in the
VTAM application definition for both nodes. If two nodes have differing values for
parallel sessions, transfers are limited by the maximum number of sessions in the
ADJACENT.NODE definition on the node where the Process is submitted.
You define the maximum number of sessions between two nodes in the network
map. Because each session has a corresponding class value, the maximum number
of sessions and maximum number of classes are equal. Selection of a Process for
execution in a given node is based on Process priority (the PRTY parameter of the
Process statement) within session class. User-specified class values allow a Process
to execute on the session having the matching class value or on sessions with
higher class values. The default class is the value specified in the Sterling
Connect:Direct network map.
When one Process completes, Sterling Connect:Direct selects another Process (if
any) to run on the available session. Sterling Connect:Direct searches until it finds
the first Process with a class eligible to execute on the available session.
A typical use for classes is to define critical Processes with low class values so that
more sessions are available for their execution. You can specify higher class
numbers for time-consuming Processes; this enables sessions with corresponding
lower class numbers to become available more frequently.
Intelligent Session Retry

The Intelligent Session Retry feature provides the ability to manage session retries
when a connection to a specific node is down so that all Processes are not retried
at the same time. This feature makes the existing connection retry facility more
efficient by reducing the extra processing overhead created when each Sterling
Connect:Direct Process retries the connection independently.
When multiple Processes are submitted for a specific node that is down, the
Processes all initially attempt to connect. When this fails, the first Process
submitted to this node continues to retry until MAXRETRIES is exceeded. The
other Processes to this node are moved to the Hold (HO) queue with a RH (held
for retry) status and are not retried. When MAXRETRIES is exceeded for the first
Process, it is moved to the Hold (HO) queue with a WC (waiting connection)
status for session retry.
After the first Process is moved to HO WC status, it can be restarted by one of the
following ways:
v You can manually release the Process causing it to be retried until a connection
is made or MAXRETRIES is exceeded, when it will return to HO WC status
55
v Another Process is submitted to this same node, causing the Process in HO WC

status to be retried until either a connection is made or MAXRETRIES is
exceeded, returning it to HO WC status
v The SNODE initiates communication with the PNODE, causing the Process in
the HO WC status to be released
When the first Process in HO WC status connects and is released, this causes the
other Processes being held in HO RH status to be released serially. Therefore, only
one Process going to an inactive node will retry until the connection is made
resulting in less overhead, since multiple Processes going to the same node are not
all attempting to retry at the same time. This also reduces the number of statistic
records which would be produced for multiple retries.
Note: The node name used by the Intelligent Retry feature is the specific name
used for the SNODE parameter. This means that if the SNODE is known by more
than one node name or TCPNAME value, only those in the queue waiting with
that value will be recognized for release.
Process Execution Example

In the following example, Sterling Connect:Direct is running. Seven Processes are
submitted to the TCQ on NODE.A to execute on NODE.B. All of the submitted
Processes are ready to run. In addition, all Processes have a user-specified class
value and the same priority. (Class determines which session Sterling
Connect:Direct selects to run. Class values allow a Process to execute on a session
with a matching class value or on sessions with higher class values.)
This site configuration enables up to four sessions to run between NODE.A and
NODE.B. Each session between NODE.A and NODE.B has its own unique class
number. Sterling Connect:Direct executes in the following order:
1. NODE.A simultaneously starts four sessions, as in the following figure.
Processes are displayed in the same order they appear in the queue. Because
the user-specified class of PROCA and PROCB is 1, they can run on the class 2,
3, or 4 sessions, if needed.
56
2. PROCB completes execution, making a session available. Sterling

Connect:Direct looks through the TCQ for the first eligible Process for that
session. PROCG is the next Process available to run on the class 2 session
because all other Processes have a class value higher than 2.
3. PROCA, PROCG, and PROCD complete execution. PROCE begins executing in

the class 3 session and PROCC begins executing in the class 4 session. The class
57
1 and class 2 sessions cannot be used because the only Process remaining in the
queue (PROCF) is class 4. PROCF must wait for an available class 4 session.
4. PROCH and PROCI are submitted. PROCF continues to wait, because it can
only run in a class 4 session.
58
5. PROCE completes. PROCF is still waiting for PROCC to complete. If another

Process is submitted for class 1, 2, or 3, it can use the available class 3 session.
.
59
Process Management in a Sterling Connect:Direct/Plex

In a Sterling Connect:Direct/Plex, the Sterling Connect:Direct Manager uses a set
of Process management rules to schedule Processes to Sterling Connect:Direct
Servers. These rules are applied in the following order:
1. The Sterling Connect:Direct Manager first checks if the remote node is running
a Sterling Connect:Direct release that supports multiple servers. If the remote
node does not support multiple servers, the Sterling Connect:Direct Manager
schedules all Processes to the Sterling Connect:Direct Server that is already
running a Process with this node, and Process management does not occur. If
the node supports multiple servers, the Sterling Connect:Direct Manager
continues with the Process management rules that follow.
2. The Sterling Connect:Direct Manager determines which Sterling Connect:Direct
Servers on the remote node can run the Process, based on the PLEXCLASS of
the Sterling Connect:Direct Server and the Process, and the current transport
support in the Sterling Connect:Direct Server.
3. The Sterling Connect:Direct Manager then determines which Sterling
Connect:Direct Server from step 2 has the lowest workload. The current Process
workload of each Sterling Connect:Direct Server is determined by dividing the
number of active Processes on the server by its MAXPROCESS initialization
parameter value.
4. If two or more Sterling Connect:Direct Servers have the lowest workload, the
Process is sent to the Sterling Connect:Direct Server that has the earliest last
scheduled time (the time of day that the Sterling Connect:Direct Server Process
is scheduled).
60
Note: If a Sterling Connect:Direct/Plex communicates with an external Sterling

Connect:Direct system, the external system must send work to the Sterling
Connect:Direct Manager to balance Process workloads in the Sterling
Connect:Direct/Plex. If an external Sterling Connect:Direct system communicates
directly with a Sterling Connect:Direct Server, work from the external system is not
distributed using Process management; the Sterling Connect:Direct Server simply
does the requested work. However, the Sterling Connect:Direct Server still informs
the Sterling Connect:Direct Manager that it is processing work, so the Sterling
Connect:Direct Manager can continue to correctly balance Process workload in the
Sterling Connect:Direct/Plex.
Also, to perform workload balancing with an external Sterling Connect:Direct
system when the Sterling Connect:Direct/Plex is the SNODE, the external system
must be a Sterling Connect:Direct version that supports the Sterling
Connect:Direct/Plex environment. You do not have to configure the external
system as a Sterling Connect:Direct/Plex. Configure it to communicate directly
with the Sterling Connect:Direct Manager.
Example: Process Management Steps

Following is an example of the steps in Process management.
1. A Sterling Connect:Direct/Plex consists of a Sterling Connect:Direct Manager
and two Sterling Connect:Direct Servers. Both Sterling Connect:Direct Servers
can process the same PLEXCLASS (CLASS1).
2. The Sterling Connect:Direct Manager receives a new Process. After determining

that both Sterling Connect:Direct Servers support the PLEXCLASS required to
run the Process, the Sterling Connect:Direct Manager determines which Sterling
Connect:Direct Server has the lowest workload.
In this case, SERVER2 has the lowest workload; it has one active Process out of
a maximum of four. The Sterling Connect:Direct Manager routes the Process to
SERVER2, and the last scheduled time of SERVER2 is updated to the current
time.
61
3. The Sterling Connect:Direct Manager has another Process to schedule. SERVER1

and SERVER2 have the same workload. However, the last Process is scheduled
to SERVER2, so the Sterling Connect:Direct Manager routes the new Process to
SERVER1.
SUBMIT Command
The SUBMIT command enables you to submit a Process to the TCQ for execution.
Parameters you specify on the SUBMIT command override any corresponding
parameters specified in the Process itself.
62
Note: If you are using the Extended Submit Facility (ESF), you can use the
SUBMIT command to submit Processes to the TCQ, even if the DTF is inactive.
The SUBMIT command has the following format. The Label is optional.
Label
SUBmit
Parameters and Subparameters
The SUBMIT command has the following parameters. The required parameters and
keywords are in bold print. Default values for parameters and subparameters are
underlined.
Label
Command
Parameters
(optional)
SUBmit
PROC= member
or
DSN= dsn | dsn(member)CASE= Yes | No
CLASS= n
DEBUG= trace settings for this Process
HOLD= Yes | No | Call
MAXDELAY= [unlimited | queued | 0 | hh:mm:ss]
NEWNAME= newname
NOTIFY= %USER | user
PACCT= 'pnode accounting data'
PLEXCLASS= (pnode class, snode class)
PNODE= primary node name
PNODEID= (ID, pswd, newpswd)
PRTY= n
REQUEUE= Yes | No
RETAIN= Yes | No | Initial
SACCT= 'snode accounting data'
SNODE= secondary node name | TCPNAME=tcpvalue;port
SNODEID= (ID, pswd, newpswd)
&symbolic 1= variable string 1
&symbolic 2= variable string 2
...=...
&symbolic N= variable string N
The following tables describes SUBMIT command parameters:

Parameter
Description
PROC = member
Specifies the Process Library member name. This name is the

member of the PUBLIB which contains the Process you are
submitting. The member name is a 1-8 character alphanumeric
string, with the first character alphabetic. This parameter is required
if the Process resides in the Sterling Connect:Direct PUBLIB.
The Sterling Connect:Direct PUBLIB PDS is specified by the
DMPUBLIB ddname allocated to the TSO session or specified in the
batch job stream.
DSN = dsn | dsn (member)
Specifies the data set name or the name of the member of a PDS that
contains the Process if the Process is not in the Sterling
Connect:Direct PUBLIB. This parameter is required if the Process
does not reside in the Sterling Connect:Direct PUBLIB.
dsn is the data set name of a sequential file that contains the
Process.
dsn(member) specifies the PDS name and member name (in
parentheses) that contains the Process. Specify either PROC or DSN;
do not specify both.
63
Parameter
Description
CASE = Yes | No
Specifies whether parameters associated with accounting data, user

ID, password, and data set name in the command and in the Process
are to be case sensitive. This parameter is optional.
CLASS = n
Determines the node-to-node session on which a Process can

execute. See your Sterling Connect:Direct administrator for which
class to specify. The range is 1-255. This parameter is optional.
DEBUG= trace
Specifies the 8-position trace setting for this Process. This parameter
enables you to specify a part trace for a particular Process. For more
information see Debug Settings in the IBM Sterling Connect:Direct for
z/OS Administration Guide.
HOLD = No | Yes | Call
Specifies whether or not the Processes are placed in the hold queue.
This parameter is optional.
No specifies that Sterling Connect:Direct does not place the Process
in the hold queue, but places it in the WAIT for execution queue
(EX). HOLD=NO is the default.
Yes specifies that the Process remains in the hold queue until either
a CHANGE PROCESS command releases the Process or a DELETE
PROCESS command deletes the Process.
When HOLD=YES and you specify a value for the STARTT
parameter, Sterling Connect:Direct places the Process submitted in
the hold queue.
Note: When RETAIN=Y, Sterling Connect:Direct ignores the HOLD
parameter.
Call specifies that Sterling Connect:Direct is to place the Process in
the hold queue until a session is established with the specified
SNODE. This session is established by either another Process
starting on the PNODE destined for the same SNODE or the
SNODE contacting the PNODE. For example, a Process submitted
with HOLD=NO establishes a session and causes execution of any
Processes residing on the SNODE destined for this node that are
submitted with HOLD=CALL.
Note: To support dial-up connections from Sterling Connect:Direct
for Microsoft Windows platforms and release Processes serially,
define the SNODE using a TCP/IP address of 0.0.0.0 (a null IP
address). You may let the port number default since it will be
resolved at connection time. Processes submitted to such nodes will
default to HOLD=CALL status and can only be released by a NULL
or ENABLE process from Sterling Connect:Direct for Microsoft
Windows. Releasing Processes to such nodes will immediately cause
them to return to HOLD=CALL status without executing because
the connection cannot be resolved. Processes initiated by such nodes
will execute normally, but will not release the HOLD=CALL
Processes. Checkpoint restart is supported for such nodes.
64
Parameter
Description
MAXDELAY = [unlimited | queued | 0 |

hh:mm:ss]
Indicates that the submit command waits until the submitted

Process completes execution or the specified time interval expires.
This parameter is optional. Do not use MAXDELAY for a submit
within a Processuse only in SUBMIT commands.
Note: If the Process does not complete within the time interval
specified by queued or hh:mm:ss, the API returns SSPA006I, RC=4
and DGADBATC terminates with RC=48 (x'30').
unlimited specifies that the submit command waits until the Process
completes execution. This is the default when no parameters are
specified.
queued specifies that the submit command waits until the Process
completes or 30 minutes, whichever occurs first.
0 specifies that the submit command attempts to start a session for
the submitted Process to execute on immediately. If Sterling
Connect:Direct cannot establish a session, after all retries are
exhausted, the Process is flushed and the submit command fails
with the error SVTM118I RC=52(x'34').
Note: If Sterling Connect:Direct cannot establish a session after all
retries are exhausted due to all available sessions on the remote
node being in use, that is, when session attempts fail with error
SVTM080I SESSION (nnn) REJECTED pname (pnum)
SNODE=remote.node, the Process is flushed and the submit
command fails with the error SVTM118I RC=12(x'0C').
MAXDELAY=0 Processes will not use the intelligent retry feature.
When a transfer to a remode node times out and retries, subsequent
transfers to the same remote node will also time out and retry rather
than being added to the wait queue.
hh:mm:ss specifies that the submit command waits for an interval
no longer than the specified hours, minutes, and seconds or until the
Process completes, whichever occurs first.
Note: If you specify MAXDELAY without the equal sign (=) and
with no parameter, MAXDELAY is set to 00:00:00 and the submit
command attempts to start a session for the submitted Process to
execute on immediately.
NEWNAME = newname
Specifies the new name of the Process. The default is the label on
the Process statement. This parameter is optional.
NOTIFY = %USER | user ID
Specifies the user ID to receive Process completion messages. This

%USER specifies that the user who submitted the Process receives
the completion messages, if the Sterling Connect:Direct user ID that
the user is currently logged on with is the same as the TSO user ID.
If the Sterling Connect:Direct user ID is different from the TSO user
ID, the TSO user is not notified but the ID to which Sterling
Connect:Direct is logged on will be notified.
user ID specifies the TSO user ID that receives Process completion
messages.
Note: The NOTIFY capability is not supported across z/OS images
in the sysplex environment. Sterling Connect:Direct cannot send
Process completion messages across z/OS images in a sysplex.
65
Parameter
Description
PACCT = 'pnode accounting data'
Accounting data for the PNODE. The maximum length of the

accounting data is 256 characters. If special characters are part of the
accounting data, you must enclose the string in single quotation
marks. This parameter is optional.
This data overrides any accounting data specified on the SIGNON
command and any accounting data specified in the Process
statement of the submitted Process.
PLEXCLASS = (pnode class, snode class)
Specifies the class that directs the Process to only certain servers in a
Sterling Connect:Direct/Plex. This parameter is only used in a
Sterling Connect:Direct/Plex and is optional.
You can designate each server in a Sterling Connect:Direct/Plex to
support only certain PLEXCLASSes through the
CDPLEX.PLEXCLASSES initialization parameter. You can then limit
Processes to only those servers by specifying the PLEXCLASS in the
Process definition.
The pnode class controls which Sterling Connect:Direct Server runs
the Process. The snode class controls what other node is used with
the Process. The pnode class and snode class are each 1-8 characters
long. An asterisk (*) indicates that the Process runs on any server
with an asterisk designated in the CDPLEX.PLEXCLASSES
initialization parameter. If you do not specify a PLEXCLASS, the
network map is checked for a default PLEXCLASS. If the network
map does not specify a default PLEXCLASS, then an asterisk is used
as the default.
If a Process must run on a specific Sterling Connect:Direct Server,
specify the Sterling Connect:Direct Server name in this field. The
Process only runs on that server.
PNODE = primary node name
Specifies the primary node of the Process. This parameter is

optional.
primary node name is a 1-16 alphanumeric character name defined
in the network map. You can express the name in alphanumerics or
nationals (@#$) with embedded periods.
The node to which you submit the Process is always the PNODE.
You do not need to specify this parameter. It defaults to the name of
the node submitting the Process. PNODE is for documentation
purposes only.
PNODEID = (ID, pswd, newpswd)
Specifies security user IDs and security passwords at the PNODE.

This parameter is optional. ID specifies the security ID that Sterling
Connect:Direct passes to a security exit for validations on the
PNODE side of the Process. The range is 1-64 alphanumeric
characters.
this parameter to validate the current security password on the
PNODE side of the Process. It can contain 1-64 alphanumeric
characters.
newpswd specifies the new security password. The security exit
uses this parameter to change the current security password to the
new security password. The range is 1-64 alphanumeric characters.
66
Parameter
Description
PRTY = n
Specifies the Process priority in the Transmission Control Queue.

High numbers indicate high priorities; low numbers indicate low
priorities. Sterling Connect:Direct uses this priority only for Process
selection; it does not affect the priority during transmission. The
default is defined during your installation. The range is from 0-15.
REQUEUE = Yes | No
Specifies whether Sterling Connect:Direct requeues a COPY step if

an ABEND occurs during processing. This parameter is optional.
Yes places the requeued Process in the HOLD queue with a status of
HELD IN ERROR (HE). You can then take corrective action and
restart the Process at the step that failed. Note that you must
explicitly release the Process from the HOLD queue when the status
is HELD IN ERROR (HE).
No specifies the failing copy step is not requeued if it fails with an
ABEND (such as X37). The remaining steps in the Process are
allowed to execute. The default is NO. The value REQUEUE=No is
forced in the case of a submit containing the MAXDELAY parameter.
RETAIN = Yes | No | Initial
Specifies whether or not Sterling Connect:Direct keeps a copy of the

Process in the HOLD queue after the Process has executed. This
Yes keeps a copy of this Process in the HOLD queue after the
Process executes. The copy of the Process does not execute until you
release it through a CHANGE Process command. If you specify
RETAIN=YES, Sterling Connect:Direct automatically holds the
Process until you release it, unless you include the STARTT
parameter in your Process. Use RETAIN in conjunction with
STARTT to cause a Process to run repeatedly at a given time each
day.
No specifies that Sterling Connect:Direct is to delete the Process after
execution. The default value for RETAIN is NO. The value
RETAIN=No is forced in the case of a submit containing the
MAXDELAY parameter.
Initial specifies that Sterling Connect:Direct is to execute the Process
every time Sterling Connect:Direct is initialized.
Note: Do not code the STARTT parameter with the RETAIN=I
parameter.
SACCT = 'snode accounting data'
Specifies the accounting data for the SNODE. The maximum length
of the accounting data is 256 characters. If you include special
characters with the accounting data, you must enclose the string in
single quotation marks. This parameter is optional.
This data overrides any accounting data specified on the SIGNON
command and any accounting data specified in the Process
statement.
67
Parameter
Description
SNODE = secondary node |

SNODE=TCPNAME |
UDT33NAM = tcpvalue;port
Specifies the secondary node used in this Process. This parameter is

optional.
secondary node name is a 1-16 alphanumeric name that is defined
in the network map.
The following characters are allowed:
A-Z, 0-9, !, @, #, $, %, &, {, }, +, -, ^
Sterling Connect:Direct for z/OS does not accept the following
characters for the SNODE:
(, ) =, \, , , <, >, |, ||
Use SNODE=TCPNAME|UDT33NAM =tcpvalue to specify TCP/IP
or UDT connections that are not defined in the network map.
tcpvalue can be a DNS name up to 255 characters or a 15-character
IPv4 or 39-character IPv6 TCP/IP address.
port is the TCP/IP port number. It can be up to 5 characters long.
Note: If the TCPNAME keyword is used and the port is not
specified, the TCP.IP.DEFAULT entry is used if the NODE is not
defined in the Netmap.
SNODEID = (ID, pswd, newpswd)
Specifies security user IDs and security passwords at the SNODE.

ID specifies the security ID that Sterling Connect:Direct passes to a
security exit for validation on the SNODE side of the Process. It can
contain 1-64 alphanumeric characters.
this parameter to validate the current security password on the
SNODE side of the Process. It can contain 1-64 alphanumeric
characters. In the case where the SNODE can Process a PassTicket
password, the PNODE generates a PassTicket when only a SNODE
user ID override is specified. The actual generation is contingent
upon the information shared in the PNODE Authorization File and
the option that generates the stage 2 security exit. The IBM Sterling
Connect:Direct for z/OS Administration Guide contains details for the
Authorization File and stage 2 security exit characteristics.
newpswd specifies the new security password. The security exit
uses this parameter to change the current security password to the
new security password. The range is 1-64 alphanumeric characters.
68
Parameter
Description
STARTT = ([date | day] [,hh:mm:ssXM])
Specifies that Sterling Connect:Direct not execute the Process until a

specified date or time. The date, day, and time are positional
parameters. If you do not specify the date or day, place a comma
before the time. This parameter is optional.
Note: Do not code STARTT with RETAIN=INITIAL.
date specifies the date to execute the Process. You can specify the
day (dd), month (mm), and year (yy for 2-digit year and yyyy for
4-digit year). You can use periods or backslashes (/) to separate the
components of a date value. You can omit the separators only for
transfers between mainframe nodes. Use separators to guarantee
transfers between all platforms.
You can use the following date formats, according to which date
order is specified in the DATEFORM initialization parameter:
v
DATEFORM=MDY specifies the date format as mm/dd/yy,

mm/dd/yyyy, mm.dd.yy, or mm.dd.yyyy
DATEFORM=DMY specifies the date format as dd/mm/yy,

dd/mm/yyyy, dd.mm.yy, or dd.mm.yyyy
DATEFORM=YMD specifies the date format as yy/mm/dd,

yyyy/mm/dd, yy.mm.dd, or yyyy.mm.dd
DATEFORM=YDM specifies the date format as yy/dd/mm,

yyyy/dd/mm, yy.dd.mm, or yyyy.dd.mm
Valid Julian dates formats are yyddd, yyyyddd, yy/ddd, yyyy/ddd,

yy.ddd, or yyyy.ddd
If you specify a date without a time, the time defaults to 00:00.
If RETAIN=YES, you cannot specify a date in the STARTT
parameter.
69
Parameter
Description
STARTT = ([date | day] [,hh:mm:ssXM])

(continued)
day specifies the day of the week that Sterling Connect:Direct is to

release the Process for execution. Valid names are MOnday, TUesday,
WEdnesday, THursday, FRiday, SAturday, and SUnday. You can also
specify TODAY, which releases the Process for execution today, or
TOMORROW, which releases the Process for execution the next day.
If you specify the day of the week with RETAIN=YES, the Process
executes the same day every week.
If you specify a day without a time, the time defaults to 00:00. A
time of 00:00 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.
hh:mm:ssXM indicates the time of day in hours (hh), minutes (mm),
and seconds (ss) that Sterling Connect:Direct is to release the
Process. You can set XM to AM or PM, or you can omit it if you are
using a 24-hour clock. You need not specify minutes and seconds.
You can express the time of day using the 24-hour clock or the
12-hour clock. If you do not use AM and PM, Sterling
Connect:Direct assumes the 24-hour clock. If you use the 12-hour
clock, you can express 01:00:00 hours as 1:00A, and 13:00 hours as
1PM. If you use the 24-hour clock, valid times are 00:00-24:00.
You can also specify NOON, which releases the Process for
execution at noon, or MIDNIGHT, which releases the Process for
execution at midnight.
If you code hh:mm:ssXM with RETAIN=YES, Sterling Connect:Direct
schedules the Process for execution the same time every day.
Note: When you specify both HOLD=YES and a STARTT value, the
HOLD specification takes precedence. Sterling Connect:Direct places
a Process submitted with HOLD=YES on the hold queue even if you
specify a start time.
&symbolic 1 = variable string 1

&symbolic 2 = variable string 2...
&symbolic N = variable string N
Specifies the default value substituted for the symbolic parameter in

the Process. If you use a symbolic in the SUBMIT command, it
overrides any default values you specify in the Process statement.
Specify a null value by immediately following the equal sign with a
comma. You must enclose a symbolic parameter containing special
characters in single quotation marks.
You can set an ampersand (&) symbolic parameter to another single
ampersand symbolic parameter that is resolved during the first
Process submission. Do not use identical symbolic names. The
maximum variable string length is 256 characters.
SUBMIT Command Examples

Use these examples to help you gain a basic understanding of how you can use
the SUBMIT command.
70
Process Example
The following example shows the syntax for a Process named PAYROLL.
SUBMIT PROC=PAYROLL HOLD=Y RETAIN=Y PACCT=1959, DEPT 27 SACCT=1962, DEPT 24 CASE=YES
In this example, the SUBMIT command was used to:

v Place the Process (named PAYROLL) in the HOLD queue.
v Retain a copy after it is released for execution.
v Create case sensitivity for fields associated with accounting data, user ID,
password, and data set name in the SUBMIT command and in the PAYROLL
Process.
Symbolic Substitution Example

In the following example, Sterling Connect:Direct resolves the symbolic &DSN in
the Process COPYSEQ upon submission:
SUBMIT PROC=COPYSEQ SNODE=CHICAGO, &DSN=MYFILE
Submitting Processes through the Batch Interface

About this task
To submit a Process through the batch interface, perform these steps:
Procedure
1. Place your SUBMIT command in the DGADBATC job stream as described in
Introduction to the Batch Interface.
Note: If the Extended Submit Facility (ESF) is available, the DTF does not need
to be running to execute your command.
Submitting Processes through the IUI

The Interactive User Interface (IUI) enables you to create, edit, and submit
Processes using the SB, DF, and CF options available on the PRIMARY OPTIONS
MENU.
IUI Submit Options

The SB, DF, and CF options available from the IUI enable you to perform the
following submit options for Processes:
Option
Description
SB
Enables you to submit Processes from the Sterling Connect:Direct PUBLIB or a

library you specify on the screen. You can also override certain parameters in the
existing Process.
71
Option
Description
DF
Enables you to edit, create, and submit Processes residing in the Sterling
Connect:Direct PUBLIB or a library you specify on the screen. You edit or create
a Process using the ISPF editor.
CF
Enables you to dynamically build a COPY Process through fill-in-the-blank

panels and submit it.
Validating Processes from the SB, DF, and CF IUI Options

From any of the IUI SUBMIT screens available through the SB, DF, and CF options,
you can validate the Process syntax without submitting the Process, or you can
submit the Process, which includes verifying the syntax, as explained in the
following table:
Operation
Related Parameter or Command
Result
Validate Process
syntax
v Enable VALIDATE ONLY

parameter
v The Process is displayed in the

VIEW PROCESS screen.
v Issue SUBV command
v If the Process is valid, the

message Submit Process for
validation command was
successful is displayed.
v If the Process is invalid, a
message identifies the problems
in the Process. You can press PF1
for information to troubleshoot
the problem.
v You can press PF3 to return to the
primary SB, DF, or CF screen.
Submit Process
and validate
syntax
v Issue SUBMIT or SUB

command
v If the Process is valid, it is

executed and a Process number is
displayed for reference.
v If the Process is invalid, a
message describes the problem.
You can press PF1 for information
to troubleshoot the syntax errors.
Using the SB IUI Option to Submit a Predefined Process

About this task
The Interactive User Interface (IUI) enables you to submit predefined Processes
using the SB option, which is available from the PRIMARY OPTIONS MENU (see
Primary Options Menu). You can submit a Process from the Sterling Connect:Direct
PUBLIB or a library you specify and override certain parameters in the existing
Process.
To submit a predefined Process from the Sterling Connect:Direct IUI:
Procedure
1. Select option SB from the Primary Options Menu to display the SUBMIT
PROCESS screen.
72
If you enable the SECURITY OVERRIDE parameter, type the security override
information in the Sterling Connect:Direct
SECURITY OVERRIDE screen.
node.name
Connect:Direct SECURITY OVERRIDE
TIME: hh:mm
CMD==>
PRIMARY NODE:
SECURITY ID: ________________________________________________
PASSWORD
:
NEW PASS
:
SECONDARY NODE:
SECURITY ID: ________________________________________________
PASSWORD
:
NEW PASS
:
2. Type the name of the Process to submit.

3. Take one of the following actions:
v To submit the Process, press Enter.
v To define additional parameters, continue with step 4.
4. Type any additional parameters of your SUBMIT command and press Enter.
For SUBMIT parameter descriptions not included in the following table, press
PF1 or see SUBMIT Command.
Field
Description
TRANSPORT
Specifies the method of transport to use for the file transfer.

NETMAPCauses Sterling Connect:Direct to search in the network
map for the sending and receiving nodes. If you type a Transport of
NETMAP, the SNODE keyword remains SNODE=secondary node.
TCPIndicates that the NODE NAME field contains an alias name or
an IP address. Sterling Connect:Direct does not look in the network
map for node information. If you type TCP in the Transport field, the
SNODE keyword becomes SNODE=TCPNAME=tcpvalue.
UDT33Indicates that the NODE NAME field contains an alias name
or an IP address. Sterling Connect:Direct does not look in the network
map for node information. If you type UDT33 in the Transport field,
the SNODE keyword becomes SNODE=UDT33NAM=udtvalue.
DNSEnables you to enter a domain name up to 255 bytes.
SECURITY
OVERRIDE
Enables you to override security information such as password and

user ID for the primary and secondary node.
Yes = Enable security overrride.
No = Do not override security information.
VALIDATE ONLY
Enables you to validate the Process syntax without submitting the

Process.
Yes = Validate without submitting the Process.
No = Do not validate without submitting the Process.
CASE
SENSITIVITY

ID, password, and data set name in the Submit Process are to be case
sensitive. The default is NO, which does not allow mixed case.
5. If you enable the SECURITY OVERRIDE parameter, type the security override
information in the Sterling Connect:Direct SECURITY OVERRIDE screen.
73
If you enable the SECURITY OVERRIDE parameter, type the security override
information in the Sterling Connect:Direct
SECURITY OVERRIDE screen.
node.name
TIME: hh:mm
CMD==>
PRIMARY NODE:
SECURITY ID: ________________________________________________
PASSWORD
:
NEW PASS
:
SECONDARY NODE:
SECURITY ID: ________________________________________________
PASSWORD
:
NEW PASS
:
6. Press Enter to perform one of the following actions:

v Submit the Process. See the table in Operation for the possible results.
v View the results of the validate-only operation in the VIEW PROCESS panel,
if you enabled the VALIDATE ONLY parameter. See the table in Operation
for the possible results.
CAUTION:
Press PF3 to exit the screen from which you submitted the Process. Each time
you press Enter, the Process is submitted.
7. If you performed the validate-only operation, press PF3 to return to the
SUBMIT PROCESS screen.
Using the DF IUI Option to Create, Edit, and Submit Processes

The Interactive User Interface (IUI) enables you to modify, create, and submit
Processes using the DF option, which is available on the PRIMARY OPTIONS
MENU. Using the DF option, you can:
v Modify a Process
v Create a new Process
v Submit a Process
v Copy statement models to create a Process
The Sterling Connect:Direct Public Process Library (PUBLIB) contains Process
statement models that you can use as templates for creating Sterling
Connect:Direct Processes. The DF option enables you to copy Process statement
models, edit them for your environment using the ISPF editor, and. submit
Processes residing in the Sterling Connect:Direct PUBLIB or in a library you
specify.
CAUTION:
Do not edit a sample member directly. Keep the source as is, edit a new name,
and then copy the member into the new one. Save as a new name. The
SDGAPROC Process library contains alias names that if edited and saved will
break the aliases.
The PUBLIB contains commented files and uncommented files. File names of
commented files are preceded by the at sign (@); file names with the pound sign
(#) prefix do not include comments.
See Validating Processes from the SB, DF, and CF IUI Options for details about
how to validate the syntax of a Process with and without submitting it.
74
Modifying and Submitting a Process Using the DF IUI Option

About this task
To modify a Process using the ISPF editor and submit the Process to the DTF:
Procedure
1. Choose option DF from the Primary Options Menu to display the
Connect:Direct PROCESS DEFINITION screen.
2. Type the member name of the Process.
3. Verify the library location and press Enter.
The PROCESS LIBRARY NAME field is required. If the member is located in
the Sterling Connect:Direct PUBLIB, type the library name that is displayed in
the PUBLIC PROCESS LIB field in the PROCESS LIBRARY NAME field.
4. After Sterling Connect:Direct displays the Process in ISPF edit mode, make the
desired changes.
5. Press PF3 to return to the PROCESS DEFINITION screen.
6. Specify case sensitivity. Case sensitivity applies to the SUBMIT command and
the Process.
v To validate the Process without submitting it, type SUBV and refer to the
table in Validating Processes from the SB, DF, and CF IUI Options on page
72 for information on the results.
v To submit the Process, type SUBMIT (or SUB) on the command line and
press Enter.
Creating and Submitting a New Process Using the DF IUI

Option
About this task
To create and submit a new Process:
Procedure
2. Type the member name of the new Process.
3. Specify the name of the library where you want to save the new Process and
press Enter.
The member location can be your private Process library (PROCESS LIBRARY
NAME) or the Sterling Connect:Direct PUBLIC PROCESS LIBRARY.
4. After Sterling Connect:Direct displays an ISPF editor screen, type your new
Process.
5. Press PF3 to save the Process in the PROCESS LIBRARY you specified and
return to the PROCESS DEFINITION SCREEN.
6. To validate the Process without submitting it, type SUBV on the command line
and press Enter. See the table in Validating Processes from the SB, DF, and CF
IUI Options on page 72 for information about the results.
the Process.
75
8. To submit the Process, type SUBMIT (or SUB) in the command line and press
Enter.
Submitting a Process Using the DF IUI Option

About this task
To submit a Process to the DTF:
Procedure
2. Type SUBMIT (or SUB) on the command line.
3. Type the member name of the Process.
4. Verify that the library name that contains the member you want to submit is
displayed in the PROCESS LIBRARY NAME field. If the member is located in
the Sterling Connect:Direct PUBLIB, type the library name that is displayed in
the PUBLIC PROCESS LIB field in the PROCESS LIBRARY NAME field.
the Process.
6. Press Enter. See the table in Validating Processes from the SB, DF, and CF IUI
Options on page 72 for information about the results.
Using Statement Models to Create a Process

About this task
To copy a Process statement model to a new PDS member:
Procedure
1. Choose option DF from the Primary Options Menu to view the Sterling
2. Type the name of the new PDS member.
3.
4.
5.
6.
Note: The PUBLIC PROCESS LIB displays the partitioned data set (PDS)
allocated by the signon CLIST or the TSO logon procedure.
Type the PROCESS LIBRARY NAME and press Enter.
Type COPY on the command line at the top of the blank member and press
Enter.
When the ISPF Edit/View-Copy screen is displayed, type the member name of
the PROCESS statement model you want to copy in the DATA SET NAME
field and press Enter.
For example, to create your Process, first copy the PROCESS statement.
Specify @PROCESS to use commented models from the PUBLIB, or
#PROCESS to use uncommented models in your Process.
To add a statement model, type a in the first column of the last line of the
new member and press Enter.
7. Repeat steps 4 through 6 to copy additional statement models into the

member following the PROCESS statement.
8. Edit the statement model or models for your environment according to the
following guidelines:
v Replace underscores with the appropriate parameter values.
76
v Provide an appropriate Process name in the PROCESS statement.

v Delete all lines that are not applicable.
v Continuation marks are necessary on all but the last line of each statement
model.
v You can delete comment lines. They are optional.
9. Press PF3 to save the changes and return to the Sterling Connect:Direct
PROCESS DEFINITION screen.
v To validate the Process without submitting it, type SUBV and press Enter.
See the table in Operation for information about the results.
v To submit the Process, type SUBMIT on the command line and press Enter.
See the table in Operation for information about the results
Using the CF IUI Option to Generate a COPY Process

The CF option of the Interactive User Interface (IUI) enables you to dynamically
generate a COPY Process through fill-in-the-blank panels and submit it.
CAUTION:
The Process generated through this option is a one-time only Process and and
there are no facilities to save the Process.
The COPY FILE Menu of the CF option displays a series of screens that collect
information to generate a SUBMIT PROCESS command. Sterling Connect:Direct
submits the predefined Process, COPYCF, with the appropriate command
parameters and variable substitutions based on your input. You can use four
screens to create the COPYCF Process:
Screen Name
Description
COPY FILE Menu Collects information for the SUBMIT COMMAND parameters,
PNODE/SNODE information, data compression, and checkpoint
information.
Security Override Collects information about user ID, password, and accounting data.
Menu
This optional panel is displayed only if you request it on the first panel.
SENDING FILE
Menu
Collects information for the Process variables for the sending file.
RECEIVING FILE Collects the information for the Process variables for the receiving file.
Menu
The following diagram illustrates the relationship of these four screens.
77
See Validating Processes from the SB, DF, and CF IUI Options for details about
how to validate the syntax of a Process with and without submitting it.
Generating a COPY Process

About this task
To generate a COPY Process:
Procedure
1. Select the CF option from the Primary Options Menu to display the COPY FILE
Menu.
node.name
Connect:Direct COPY FILE MENU
TIME: hh:mm
CMD ==>
SENDING
ENVIRONMENT: ZOS______
TRANSPORT: NETMAP
NODE NAME: CD.NODE1___________________________________________________
RECEIVING ENVIRONMENT: ZOS______
NODE NAME: CD.NODE2___________________________________________________
PROCESS NAME: COPYCF__
CLASS:
___
(NUMERIC)
VALIDATE ONLY ==> N
HOLD:
N
(Y, N, OR C-CALL)
NOTIFY USER:
%USER___________________________________________________________
PRIORITY:
__
(RANGE: 0 TO 15)
REQUEUE:
N
(Y OR N)
RETAIN ON TCQ: N
(Y, N, OR I-INITIAL)
START DATE:
__________ TIME: __________
CHECKPOINT:
________
(BYTE INTERVAL - NK|NM)
DEBUG:
________
(HEXADECIMAL)
PLEXCLASS:
________ ________ (PNODE SNODE)
COMPRESS:
N____
(Y, N, X-EXTENDED, XXX, OR CC)
EXT COMPRESSION LEVEL: _ WINDOW: __ MEMORY: _
OVERRIDE SECURITY: N
(Y OR N)
DO YOU WANT VALUES FOR THIS COPY TO BE CASE SENSITIVE? ==> NO___
2. If necessary, rename the COPYCF Process by typing a name in the PROCESS

NAME field.
3. For descriptions of SUBMIT parameters not included in the following table,
press PF1 or see SUBMIT Command.
78
Parameter Name
Description
SENDING
ENVIRONMENT
Specifies the operating system or platform from which the file is

transmitted. The values you place in the Sending Environment and
Node Name fields determine which Sending File screen is displayed.
Parameter Name
Description
NODE NAME
Specifies the name of the Sterling Connect:Direct node from which the
file is transmitted.
TRANSPORT
Specifies the method of TRANSPORT Sterling Connect:Direct uses for

the file transfer.
NETMAPCauses Sterling Connect:Direct to look in the network map
for the sending and receiving nodes. If you type a Transport of
NETMAP, the SNODE keyword remains SNODE=secondary node.
TCPIndicates that the NODE NAME field contains an alias name or
an IP address. Sterling Connect:Direct does not look in the network
map for node information.
UDT33Indicates that the NODE NAME field contains an alias name
or an IP address. Sterling Connect:Direct does not look in the network
map for node information. If you type UDT33 in the Transport field,
the SNODE keyword becomes SNODE=UDT33NAM=udtvalue.
DNSEnables you to enter a domain name up to 255 bytes
Note: If you type TCP or DNS in the Transport field, the SNODE
keyword becomes SNODE=TCPNAME=tcpvalue.
RECEIVING
ENVIRONMENT
Specifies the operating system or platform to which the file is

transmitted. The values you place in the Receiving Environment and
Node Name fields determine which Receiving File screen is displayed.
NODE NAME
Specifies the name of the node to which the file is transmitted.
PROCESS NAME
(optional) Specifies the name to be used under which the Process will
be submitted. If you do not type a Process name, Sterling
Connect:Direct provides the default name COPYCF.
VALIDATE ONLY
Enables you to validate the Process without submitting it.

YES = Validate the Process, but do not submit it.
NO = Do not validate before the Process is submitted.
CHECKPOINT
(optional) Specifies the byte interval for checkpoint support, which

enables restart of interrupted transmissions at the last valid
transmission point, avoiding the need to restart transmission from the
beginning.
K denotes thousands; M denotes millions. A checkpoint value of zero
stops automatic checkpointing.
COMPRESS
(optional) Specifies whether and how the data being transmitted

should be compressed.
Y Uses compression with X'40' (blank) as the PRIMEchar.
N Does not use compression.
X Uses Extended compression.
X'xx' Uses compression with the specified xx' hex vale.
C'c' Uses compression with the specified cc' character value.
Note: Compression is CPU-intensive, and its effectiveness is data
dependent. It should only be used if its benefits are known.
79
Parameter Name
Description
EXT
COMPRESSION
LEVEL
Note: The effects of changing the default values for the extended
compression parameters (level, window, and memory) are not always
predictable and can significantly increase CPU utilization. Before
changing the default values, see Improving Performance in the IBM
Sterling Connect:Direct for z/OS Administration Guide.
(optional) Specifies the value from 19 indicating the degree of
compression to use. The default is 1, which usually provides sufficient
compression.
WINDOW
(optional) Specifies the value from 815 indicating the size of the
compression buffer to use. The default of 13 equals 32 KB.
MEMORY
(optional) Specifies the value from 19 indicating the amount of

memory used to maintain the compression state. The default of 4
equals 8 KB.
OVERRIDE
SECURITY
Enables you to change security information for the sending and

receiving nodes.
YES = Enable
NO = Disable
CASE
SENSITIVITY
(optional) Specifies the case sensitivity not only to the SUBMIT

command, but to the COPY Process itself. Sterling Connect:Direct
provides for mixed case user input because some platforms allow it.
The default is NO, which does not allow mixed case.
4. To override security information, type Y in the OVERRIDE SECURITY field.

node.name
TIME: hh:mm
CMD ==>
SENDING
ENVIRONMENT: ZOS
TRANSPORT: TCP
NODE NAME:
CD.NODE1
SECURITY ID: ________________________________________________________________
PASSWORD
:
NEW PASS
:
ACCOUNTING DATA: ____________________________________________________
RECEIVING ENVIRONMENT: ZOS
NODE NAME:
CD.NODE2
SECURITY ID: ________________________________________________________________
PASSWORD
:
NEW PASS
:
ACCOUNTING DATA: ____________________________________________________
5. In the SECURITY OVERRIDE screen:

a. Specify the security information for the node whose security you want to
override and press Enter. This procedure assumes that you modify security
information for both nodes.
b. Press PF1 for a description of each field.
Note: For a complete description of the valid parameters of a COPY
Statement and examples to help you fill in both the SENDING FILE and
RECEIVING FILE screens, see the Connect:Direct Process Language help.
6. When the SENDING FILE screen for the environment and node name you
specified is displayed, type appropriate values and press Enter.
80
Note: If the data set name does not follow z/OS naming conventions, enclose
the data set in single quotation marks. An HFS file must begin with a slash (/)
and can contain up to 251 bytes.
node.name
COPYFILE - SENDING FILE (z/OS or OS/390)
TIME: hh:mm
CMD ==>
NODE NAME: CD.NODE2
SENDING DSNAME:
____________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
______________________________
UNIT PARAMETER: ( ________________________________ )
LABEL PARAMETER: ( ________________________________ )
VOLUME SERIAL(S):( _______________________________________________________ )
RETAIN: _ (Y OR N)
DCB PARAMETER:
( ________________________________________________________ )
TYPE KEY:
________
MSVGP NAME: ________
SYSOPTS: _____________________________________________________________________
(PDS ONLY:)
REPLACE: Y (Y OR N)
ALIAS: Y (Y OR N)
SELECTION CRITERIA: ( __________________________________________ )
( __________________________________________ )
EXCLUSION CRITERIA: ( __________________________________________ )
( __________________________________________ )
7. When the RECEIVING FILE screen for the environment and node name you
specified is displayed, type appropriate values and press Enter.
Note: If the data set name does not follow z/OS naming conventions, enclose
the data set in single quotation marks. An HFS file must begin with a slash (/)
and can contain up to 251 bytes.
node.name
COPYFILE - RECEIVING FILE (z/OS or OS/390)
TIME: hh:mm
CMD ==>
NODE NAME: Q1A.ZOS.V4600
RECEIVING DSNAME: ____________________________________________________________
________________________________________________________________________________
________________________________________________________________________________
______________________________
DISPOSITION:
( NEW , CATLG_ , ______ )
UNIT PARAMETER: ( ________________________________ )
VOLUME SERIAL(S):( _______________________________________________________ ) )
RETAIN: _ (Y OR N)
COUNT: ___ (1-255)
DCB PARAMETER:
( __________________________________________________________ )
LABEL PARAMETER: ( ____________________________________________ )
SPACE:
( ________________________________ )
TYPE KEY:
________
MSVGP NAME: ________
SYSOPTS: _____________________________________________________________________
SMS: DATA CLASS: ________ STORAGE CLASS: ________ MGMT CLASS: _________
AVERAGE RECORDS: _
DSNTYPE
: _______
VSAM ORGANIZATION: ____ KEY LENGTH: ___
KEY OFFSET: _____
LIKE DSNAME:
____________________________________________
SECURITY MODEL: ____________________________________________
GENERIC MODEL: ___ (YES OR NO)
8. Press Enter.
v If you enabled the Validate Only parameter, a VIEW PROCESS screen with
your Process is displayed. See the table in Operation for information on the
results.
v If you did not select the Validate Only option, the Process is executed. See
the table in Validating Processes from the SB, DF, and CF IUI Options on
page 72 for information on the results.
81
CAUTION:
Press PF3 to back out of each screen until the Primary Options Menu is
displayed. Each time you press Enter, the Process is submitted.
82
Chapter 7. Controlling Processes in the TCQ

Controlling Processes with Commands
Sterling Connect:Direct Processes consist of statements with parameters that
provide instructions for copying files, running jobs and programs, and altering the
sequence of Process step execution. Use the Process Control commands to
manipulate these Processes while they are in the TCQ.
Note: You can also use the Sterling Connect:Direct Browser User Interface to
perform some Sterling Connect:Direct for z/OS procedures.
Setting Selection Criteria

The Process control commands have common parameters and IUI screen layouts.
All Process control commands allow you to select Processes by Process name,
number, and submitter. (Some allow additional criteria.) The WHERE parameter
groups the selection arguments, enabling you to make common changes or
selections. The command applies to all Processes which match the criteria. For
example, if you indicate a Process name PROCA with no further qualification, all
Processes named PROCA are affected by the command.
When you specify two or more WHERE subparameters, you further qualify the
selection so that all conditions must be satisfied. In this way, you can adequately
qualify your selection if you have non-unique Process names or numbers. For
example, if you specify in your selection criteria a Process name of PROCA and
Process number of 16, the Process number of PROCA must be 16 for the command
to apply.
If you specify multiple Processes by using the list option on the subparameter, the
position of the arguments in the list is significant. Elements in each list must
correspond by position. For example, PNAME=(PROCA, PROCB), PNUM=(16,17)
requires that PROCA be Process number 16 and PROCB be Process number 17 for
the command to apply.
On the screens, you can type a list of Process names, numbers, and submitters
(user ID and node ID) to obtain the same results that the WHERE parameter list
provides in batch. Sterling Connect:Direct builds the appropriate command from
the screen. Sterling Connect:Direct accesses the corresponding Process names and
numbers and submitters (user ID and node) from left to right to construct the list
form of this command.
Modifying a Process in the TCQ with CHANGE PROCESS

Use the CHANGE PROCESS command to modify the parameters of a Process
when the Process is in the TCQ in a nonexecuting state. Release a held Process or
restart a failed Process with this command. (You can also release a held Process
through the Operator Table and Selected Process screens by typing an R next to the
Process Name.)
CHANGE PROCESS Command Format

The CHANGE PROCESS command has the following format and associated
parameters. Required parameters and keywords are in bold print.
83
Label
Command
Parameters
(optional)
CHange PROCESS
WHERE ( NODE= node name | (list)

PNAME= name | (list)
PNUMber= number | (list)
SUBmitter= (node name, user ID)|(list)
)
CASE= Yes | No
CLASS= n
DEBUG= trace bits
DEST= destination node
HOLD= Yes | No | Call
NETMAP.REFRESH
PLEXCLASS=(pnode class, snode class)
PRTY= n
RELEASE
RESTART= [NO |
FIRST = volume sequence number |
FIRST = SER = volume serial number |
LAST = volume sequence number |
LAST = SER = volume serial number |
VOLCNT = n]
RETAIN= Yes | No | Initial
STARTT= ([date|day] [,hh:mm:ssXM])
The following table describes the parameters for the CHANGE PROCESS
command:
Parameter
Description
WHERE (NODE = node name | (list) PNAME Specifies which Process(es) to change. Name multiple Processes in
= name | (list)
the command using the selection criteria method described on
Setting Selection Criteria on page 83 if you have to make similar
PNUMber = number | (list)
changes to many Processes. This parameter is required.
SUBmitter = (node name, user ID) | (list))
The selection subparameters are optional; however, you must

specify at least one of NODE, PNAME, PNUMBER, or SUBMITTER.
These subparameters are special in that they identify which
Processes are selected for the change activity defined by the other
parameters.
NODE = node name | (list)
Specifies the snode or a list of snodes where the Processes to be

changed are running. If you specify a list of snodes, enclose them in
parentheses separate each snode with a comma.
You can use this subparameter with the HOLD parameter to put all
Processes on a node on hold if the node is unavailable, or if
problems exist with the node. You can restart all Processes later
using the RESTART parameter with the NODE= subparameter.
PNAME = name | (list)
Specifies the name of the Process to be changed or a list of Process

names enclosed in parentheses and separated by commas. This
Specifies the number of the Process to be changed or a list of

Process numbers enclosed in parentheses and separated by commas.
The range is 1-99999.
SUBmitter = (node name, user ID) | (list)
Specifies the node name and user ID of the user that submitted the
Process to be changed. Specify a list of SUBmitter IDs by enclosing
the IDs in parentheses and separating them by commas.
84
Parameter
Description
CASE = Yes | No

ID, password, and data set name are case sensitive. The designation
refers only to the command, not to the Process itself. See Indicating
Case Sensitivity for a general overview of case sensitivity. This
CLASS = n
Determines the node-to-node session on which a Process executes.

Consult your Sterling Connect:Direct administrator for instructions
concerning which class to specify. The range is 1-255. This
DEBUG= trace settings for this Process
Specifies the 8-position trace setting for this Process. This parameter
enables you to specify a trace for only this Process. The table on
Building, Modifying, and Submitting Processes lists acceptable trace
values. This parameter is optional.
Note: This option can generate a large amount of output and
should be used with caution.
DEST = destination node
Specifies a new destination node. This parameter changes the node

that this Process communicates with. This parameter is optional.
HOLD = Yes | No | Call
Specifies whether or not the Process is placed in the hold queue.

Yes specifies that the Process remains in the hold queue until one of
the following events occurs:
v CHANGE PROCESS releases the Process
v DELETE PROCESS deletes the Process
When you specify both HOLD=YES and a STARTT value, the
HOLD specification takes precedence. Therefore, Sterling
Connect:Direct places a Process submitted with HOLD=YES on the
hold queue even if you specified a start time.
No specifies that Sterling Connect:Direct does not place the Process
in the hold queue, but places it in the WAIT for execution queue
(EX). HOLD=NO is the default.
Call specifies that Sterling Connect:Direct is to place the Process in
the hold queue until a session is established with the specified
SNODE. This session could be established by either another Process
starting on the PNODE destined for the same SNODE or the
SNODE contacting the PNODE. For example, a Process submitted
HOLD=NO establishes a session and causes execution of any
Processes residing on the SNODE destined for this node that are
submitted with HOLD=CALL.
Note: Sterling Connect:Direct ignores the HOLD parameter if
RETAIN=Y.
NETMAP.REFRESH
Refreshes the network map for Processes waiting execution in the

Wait queue, after an UPDATE NETMAP command is issued for this
node. (For a description of the UPDATE NETMAP command, see
the IBM Sterling Connect:Direct for z/OS Administration Guide and
search on Maintaining the Network Map. This parameter is
optional.
Do not use the NETMAP.REFRESH parameter if the network map
protocol is changed (for example, changing a node from LU0 to
LU6.2). If you change the protocol for a particular node, you must
delete and resubmit all waiting Processes for that node.
85
Parameter
Description
PLEXCLASS = (pnode class, snode class)
Specifies the class that directs the Process to only certain servers in
a Sterling Connect:Direct/Plex. This parameter does not apply to a
Sterling Connect:Direct Stand-alone Server. This parameter is
optional.
You can designate each server in a Sterling Connect:Direct/Plex to
support only certain PLEXCLASSes through the
CDPLEX.PLEXCLASSES initialization parameter. You can then limit
Processes to only those servers by specifying the PLEXCLASS in the
Process definition.
The pnode class controls which Sterling Connect:Direct Server runs
the Process. The snode class controls what other node is used with
the Process.
The pnode class and snode class are each 1-8 characters long. An
asterisk (*) indicates that the Process runs on any server with an
asterisk designated in the CDPLEX.PLEXCLASSES initialization
parameter. If you do not specify a PLEXCLASS, the network map is
checked for a default PLEXCLASS. If the network map does not
specify a default PLEXCLASS, then an asterisk is used as the
default.
If a Process must run on a specific Sterling Connect:Direct Server,
specify the Sterling Connect:Direct Server name in this field. The
Process only runs on that server.
PRTY = n
Specifies the Process priority in the Transmission Control Queue.

High numbers indicate high priorities; low numbers indicate low
priorities. Sterling Connect:Direct uses this priority only for Process
selection; it does not affect the priority during transmission. The
default is set by the PRTYDEF global initialization parameter. The
range is from 0-15. This parameter is valid for LU0 only. This
RELEASE
Releases the Process for execution from the queue where it is

currently residing. Either specify RELEASE or omit it. Releases or
RELEASE=no is not valid. This parameter is optional.
86
Parameter
Description
RESTART = [NO | FIRST = volume sequence

number | FIRST=SER=volume serial number
|
Specifies the conditions for restarting an interrupted Process.
LAST = volume sequence number |

LAST = SER = volume serial number |
VOLCNT = n]
Use the CHANGE PROCESS command to cause Sterling

Connect:Direct to restart a data transmission at the last checkpoint
position taken before the interruption or at a previous checkpoint
position. Sterling Connect:Direct restarts the copy step at the
position you specify. This parameter is optional.
NO specifies that the copy step restarts at the beginning of the
transmission.
FIRST=volume sequence number specifies that the copy step
restarts at the beginning of the volume designated by the volume
sequence number.
FIRST=SER=volume serial number specifies that the copy step
restarts at the beginning of the volume serial given.
LAST=volume sequence number specifies that the copy step
restarts at the end of the volume designated by the volume
sequence number. LAST specifies that the copy step restarts at the
last block on the volume if the output is disk or the last checkpoint
on the volume if the output is tape.
LAST=SER=volume serial number specifies that the copy step
restarts at the end of the volume serial given. LAST specifies that
the copy step restarts at the last block on the volume if the output is
disk or the last checkpoint on the volume if the output is tape.
VOLCNT=n specifies that the volume count on the interrupted
copy step is changed to the value specified. You can use this
parameter to increase the number of output volumes if the copy
step is interrupted because the volume count of that step is too
small.
RETAIN = Yes | No | Initial
Specifies whether or not Sterling Connect:Direct keeps a copy of the

Process in the HOLD queue after the Process has executed. This
Yes keeps a copy of this Process in the HOLD queue after the
Process executes. The copy of the Process does not execute until you
release it through a CHANGE Process command. If RETAIN=YES is
specified, Sterling Connect:Direct automatically holds the Process
until you release it, unless you include the STARTT parameter in
your Process. Use RETAIN in conjunction with STARTT to cause a
Process to run repeatedly at a given interval.
No specifies that Sterling Connect:Direct is to delete the Process
after execution. The default value for RETAIN is NO.
Initial specifies that Sterling Connect:Direct is to execute the Process
every time Sterling Connect:Direct is initialized. Do not code the
STARTT parameter with the RETAIN=I parameter.
STARTT =
( [ date | day] [,hh:mm:ssXM ])
Specifies that the Process not execute until a specified date or time.
See SUBMIT Command on page 62 for a complete explanation of
the STARTT parameter. This parameter is optional. When changing
the date, day, or hh:mm:ssXM, you must respecify even the values
that do not change. You cannot specify TODAY or TOMORROW for
the day subparameter.
87
Note: Processes with a QUEUE or STATUS of PR cannot be changed with the

CHANGE PROCESS command.
CHANGE PROCESS Command Examples

The following CHANGE PROCESS command places the Processes named
PAYROLL and BILLING in the hold queue:
CH PROC WHERE ( PNAME=(PAYROLL, BILLING)) HOLD=Y
In the following example, the Process named PAYROLL is changed so that the new
destination node is DALLAS1 and the Process executes every Friday:
CH PROC WHERE (PNAME=PAYROLL) DEST=DALLAS1 RETAIN=Y STARTT=(FR)
In the following example, the Process called PAYROLL with the Process number of
60584 has the RETAIN status changed so that the Process is deleted after execution:
CH PROC WHERE (PNUM=60584, PNAME=PAYROLL) RELEASE RETAIN=N
Issuing CHANGE PROCESS through the Batch Interface

About this task
To use the CHANGE PROCESS command from the Batch Interface:
Procedure
1. Place commands in the DGADBATC job stream as described in Sample Job
Stream to Run the Batch Interface.
A report similar to the following is displayed:
===================================================================
CHANGE PROCESS
===================================================================
PROCNAME PROCNUM_ SUBMITTER_NODE__ SNODE.NAME______ MESSAGE________
USERID___________
------------------------------------------------------------------DMNOTEST 271
node.name
node.name
DEST CHANGED
USER01
-------------------------------------------------------------------
3. Check this report to verify your results.
88
Issuing CHANGE PROCESS through the IUI

About this task
Use the CHANGE PROCESS screen to change a Process and its parameters. To
issue the CHANGE PROCESS command from the Sterling Connect:Direct IUI,
perform the following steps:
Procedure
1. Select option CP from the Primary Options Menu to display the CHANGE
PROCESS screen.
node.name
CHANGE PROCESS
hh:mm
CMD ==>
==> ______
==> ______
==> ______
PROCESS NAMES:
==> ________
==> ________
==> ________
==> ________
NODES
==> _______________
==> _______________
==> _______________
USER IDS:
USER NODES:
==> _________________________________________________________________
==> ____________________________
==> _________________________________________________________________
==> ___________________________
==> _________________________________________________________________
==> ____________________________
PLEXCLASS
==> ________ ________ (PNODE SNODE)
DESTINATION NODE
==> ________________
DEBUG ==> ________
PRIORITY
==> __
(0 TO 15)
CLASS
==> ___
HOLD PROCESS
==> _
(Y-YES, N-NO, C-CALL)
RELEASE PROCESS
==> _
(Y-YES, N-NO)
RETAIN PROCESS
==> _
(Y-YES, N-NO, I-INIT)
REFRESH FROM NETMAP ==> _
(Y-YES, N-NO)
SCHED. START
DATE ==> ________
TIME ==>______
RESTART ALTERATIONS ==> _________________________________________________
DO YOU WANT THE VALUES OF THIS REQUEST TO BE CASE SENSITIVE? ==> NO
Sterling Connect:Direct selects the corresponding Process names and numbers

and submitters (user ID and node) from left to right to construct the list form
of this command. This list fully qualifies your search criteria.
2. Type at least one of the parameters or a combination of parameters as
described in the CHANGE PROCESS command syntax section on Modifying a
Process in the TCQ with CHANGE PROCESS or press the PF1 key for Help.
Sterling Connect:Direct changes the parameters for the Processes that match the
search criteria. The case sensitivity designation refers only to the command
parameters on the screen, not to the parameters of the Process itself.
Suspending, Flushing, and Deleting Processes

The SUSPEND PROCESS, FLUSH PROCESS, and DELETE PROCESS commands
have similar formats and parameters. The following table describes each command:
Process
Description
SUSPEND
PROCESS
Terminates execution and puts an executing Process in the Hold queue.

Sterling Connect:Direct places the Process in HOLD status. You can
restart the Process through the RELEASE parameter of the CHANGE
PROCESS command, or by using the R option on the Operator Table
screen or the Selected Process screen.
89
Process
Description
FLUSH PROCESS Terminates an executing Process. Note that if you specify RETAIN=YES,
the flushed Process remains in the TCQ for execution at the next
scheduled time. If you specify RETAIN=NO, Sterling Connect:Direct
removes the Process from the TCQ, and you must resubmit it if you
want it to execute.
DELETE
PROCESS
Enables you to specify a nonexecuting Process and remove it from the

TCQ.
Note: FLUSH PROCESS stops an executing Process.
If you do not specify FORCE for the FLUSH or SUSPEND command, an indicator
notifies the program executing on behalf of the Process that a FLUSH or SUSPEND
command was issued for the Process. If that program is not in control (for
example, if it is waiting on a request outside of Sterling Connect:Direct code to
complete), then it does not see the FLUSH or SUSPEND indicator and the Process
is not flushed or suspended; otherwise, the program looks for the FLUSH or
SUSPEND indicator and takes the appropriate action.
When you specify FORCE, the action taken depends on the STATE and SUBSTATE
of the Process for which you issued the FORCE FLUSH or FORCE SUSPEND.
Determine the STATE and SUBSTATE of the Process by doing a SELECT PROCESS
or SELECT TASK command.
Note: For a Process in a VTAM I/O STATE and a SUBSTATE of SEND or
RECEIVE, the FLUSH or SUSPEND command is implemented whether you specify
FORCE or not. That is not true for the other states.
SUSPEND, FLUSH, or DELETE PROCESS Command Format

The SUSPEND PROCESS, FLUSH PROCESS, and DELETE PROCESS commands
have the following format and associated parameters. Required parameters and
keywords are in bold print.
Label
Command
Parameters
(optional)
FLUSH PROCess |
DELETE PROCess |
SUSPEND PROCess
WHERE (
FORCE
)
Note: The FORCE parameter is not valid for
DELETE PROCESS.
CASE = Yes | No
The following table describes the parameters:
90
Parameter
Description
WHERE (
Specifies which Process to suspend, delete, or flush. Name multiple Processes in the
command using the search criteria method described on Setting Selection Criteria on
page 83.

PNUMber = number |
(list)
SUBmitter = (nodeid,
user ID) | (list)
FORCE )
WHERE is the only required parameter for the SUSPEND PROCESS, DELETE PROCESS,
and FLUSH PROCESS commands. Its subparameters are optional. However you must
specify at least one of the PNAME, PNUMBER, and SUBMITTER subparameters.
PNAME = name | (list) specifies the name of the Process or a list of Process names
enclosed in parentheses and separated by commas.
PNUMber = number | (list) specifies the number of the Process selected or a list of
Process numbers enclosed in parentheses and separated by commas. The range is 1-99999.
SUBmitter = (nodeid, user ID) | (list) specifies the nodeid and user ID of the user that
submitted the Process. Specify a list of SUBmitter IDs by enclosing the IDs in parentheses
and separating them by commas.
FORCE enables you to suspend or flush a Process waiting for unavailable resources. If
the initial suspend or flush fails, retry the command with FORCE.
Note: FORCE parameter is not valid for DELETE PROCESS. If FORCE is specified for a
Process executing on an LU6.2 session, it can terminate the session immediately, and
Sterling Connect:Direct does not exchange the Process statistics between nodes.
CASE = Yes | No
Specifies whether parameters associated with accounting data, user ID, password, and
data set name are case sensitive. The designation refers only to the command, not the
Process itself. This parameter is optional.
Note: Processes with a QUEUE or STATUS of PR cannot be flushed or suspended

with the FLUSH or SUSPEND PROCESS command.
SUSPEND, FLUSH, and DELETE Command Examples

Examples of the SUSPEND, DELETE, and FLUSH commands are shown in the
following:
SUSPEND Process
The following command suspends any executing Process with a submitter node ID
of DALLAS and a submitter user ID of SMITH:
SUSPEND PROC
WHERE (SUB=(DALLAS, SMITH))
The following command suspends the Process named PAYROLL, which is Process
number 514 and the Process named COPY100, which is Process number 575.
SUS PROC WHERE ( PNAME=(PAYROLL,COPY100), PNUM=(514,575))
FLUSH Process
The following command flushes executing Processes submitted by SMITH at the
node DALLAS:
FLUSH PROC
WHERE (SUB=(DALLAS, SMITH))
91
The following command flushes the Process named PAYROLL which has Process
number of 514 and the Process named COPY100 which has the Process number of
575:
FLUSH PROC WHERE ( PNAME=(PAYROLL,COPY100), PNUM=(514,575))
DELETE Process
The following command deletes Processes with the number 60584:
DEL PROC
WHERE (PNUM=60584)
The following command deletes all Processes submitted by CHUCK at the node
DALLAS.MVS:
DEL PROC
WHERE (SUB=(DALLAS.MVS, CHUCK))
The following command deletes all Processes in the PR queue. When specifying
QUEUE= PR, no other selection criteria are allowed.
DELETE PROCESS WHERE (QUEUE=PR)
Issuing the SUSPEND PROCESS, DELETE PROCESS, or

FLUSH PROCESS Commands through the Batch Interface
About this task
To use the SUSPEND PROCESS, DELETE PROCESS, or FLUSH PROCESS
commands from the Batch Interface, perform the following steps:
Procedure
1. Place commands in the DGADBATC job stream as described in Sample job
stream to run the batch interface on page 10.
3. Verify the results.
Issuing the SUSPEND PROCESS, DELETE PROCESS, or

FLUSH PROCESS Commands through the IUI
About this task
To issue commands through the IUI:
92
Procedure
1.
Access the function that you want as described in the following table.
Function
Access Method
Suspend an
executing Process
Select option PS from the Primary Options Menu.

Type SUS at the Primary Options Menu command prompt
Type a P next to the Process Name on the Operator Table, the
Operator Table - Executing Queue, or the Selected Process screens.
Delete a
nonexecuting
Process
Select option DP from the Primary Options Menu.
Flush a Process
Select option FP from the Primary Options Menu.
Type a D next to the Process Name on the Operator Table or the

Selected Process screens.
v Type an F next to the Process Name on the Selected Process screen.
The following screen shows an example of the Suspend an Executing Process

screen. The Delete A Nonexecuting Process screen and the Flush Process screen
are similar except that the FORCE option is not on the Delete A Nonexecuting
Process screen.
node.name
SUSPEND AN EXECUTING PROCESS
hh:mm
CMD ==>
PROCESS NUMBERS:
==> ______
==> ______
==> ______
==> ______
==> ______
==> ______
==> ______
==> ______
PROCESS NAMES:
==> ________
==> ________
==> ________
==> ________
==> ________
==> ________
==> ________
==> ________
FORCE: (Y-YES, N-NO) FORCE SUSPENDING A PROCESS ON AN LU 6.2 SESSION
==> _
MAY TERMINATE THE SESSION IMMEDIATELY WITHOUT
STATISTICS OF THE PROCESS BEING EXCHANGED
USER IDS:
USER NODES:
==> _______________________________________________________________
==> ___________________________
==> _______________________________________________________________
==> ___________________________
==> _______________________________________________________________
==> ___________________________
DO YOU WANT THE VALUES OF THIS REQUEST TO BE CASE SENSITIVE? ==> NO
Sterling Connect:Direct builds the SUSPEND PROCESS command from this

screen, and selects the corresponding Process names and numbers and
submitters (user ID and node) from left to right to construct the list form of this
command. This list fully qualifies your search criteria.
2. Type at least one of the parameters or a combination of parameters as
described in the SUSPEND PROCESS command syntax section in Suspending,
Flushing, and Deleting Processes, or press the PF1 key for Help. Sterling
Connect:Direct suspends the Processes which match your search criteria.
Note: Case sensitivity designation refers only to the command parameters on
screen, not to the parameters of the Process.
3. To minimize the risk of deleting, suspending, or flushing a Process accidentally,
you may be required to confirm a Process request before it is executed. If you
are required to confirm delete, flush, and suspend commands, a panel similar
to the following screen is displayed. Do one of the following:
93
v To confirm the operation, type Y on the command line. Sterling

Connect:Direct performs the function and returns to the previous screen.
v To return to the previous screen without performing the function, press PF3.
To change the Process numbers, select this option before executing the
command.
DMDELCN2
Connect:Direct Confirm Delete Command
DATE: YYYY/MM/DD
TIME: HH:MM
CMD ==>
You have requested the following process(es) be deleted, are you sure this is
what you want to do?
Reply Yes, No or CANCEL or Press PF3 to Cancel the Request
Process Numbers
==> 123
==>
==>
==>
==>
==>
Process Names
==>
==>
==>
==>
==>
==>
USER IDS: USER NODES:
==>
==>
==>
==>
==>
==>
==
==>
__ Do not display this Confirm Delete prompt again.
Note: If you see the option, Do not display this Confirm Delete prompt again,
you can type an X next to this option to turn off the Confirm prompt so that it
will not display again during the current session.
Examining Processes in the TCQ

Use SELECT PROCESS to look over Processes in the TCQ. You can specify the
search criteria and the form in which the information is presented (file, printout,
table, or screen display).
Note: Use the SELECT STATISTICS command to determine the outcome of a
completed Process.
SELECT PROCESS Command Format

The SELECT PROCESS command has the following format and parameters. The
required parameters and keywords are in bold print. Default values are
underlined.
Note: The syntax and parameters for the VIEW PROCESS command are identical.
Label
Command
Parameters
(optional)
SELect PROCess
WHERE (
DEST= node | (list)
QUEUE= All | queue name
SERVER= server name
STATUS= Process status | (list)
CASE= Yes | No
FILE | PRint | TABle
or
View PROCess
94
The following table describes the parameters.

Parameter
Description
WHERE
(DEST = node | (list)
QUEUE = All | Exec | Hold | Timer
| Wait
STATUS = Process status | (list)
SERVER = server name | (list)
SERVER = server name | (list)
SUBmitter = (node name, user
ID) | (list) )
Specifies which Processes to select. Name multiple Processes in the

command using the search criteria method described on Setting
Selection Criteria on page 83. The subparameters PNAME,
PNUMber, and SUBmitter are optional, but you must specify at least
one.
WHERE is the only required parameter for the SELECT PROCESS
command. Not all its subparameters are required.
DEST = node | (list) specifies the destination node name of the
Process you are selecting or a list of destinations enclosed in
parentheses and separated by commas.
PNAME = name | (list) specifies the name of the Process or a list of
Process names enclosed in parentheses and separating by commas.
95
Parameter
Description
PNUMber = number | (list) specifies the number of the Process you
are selecting or a list of Process numbers enclosed in parentheses
and separated by commas. The range is 1-99999.
QUEUE = All | queue name specifies Process selection based on the
TCQ. Values are: All specifies selection of a Process from all queues.
This value is the default. queue name can be one of the following:
E = Executing queue
H = Hold queue
PR = Retain queue
T = Timer queue
W = Wait queue
SERVER = server name | (list) selects Processes on the specified
Sterling Connect:Direct Servers. The server name is a 1-8 character
name assigned to each server in a Sterling Connect:Direct/Plex
through the CDPLEX.SERVER initialization parameter.
STATUS = Process status | (list) specifies Process selection by status
value or a list of status values in parentheses separated by commas.
Values include:
H = All Held Processes
HC = Held for Call
HE = Held for Error
HI = Held Initially
HO = Held by Operator
HP = Held due to Process error
HR = Held Retain
HS = Held for Suspension
PR = Retained after Execution
R = All Restart Processes
RA = Held for Restart due to Allocation error
RH = Restart Held (may be due to the Intelligent Retry feature)
W = All Waiting Processes (including Retry)
WC = Wait for Connection
WT = Waiting for Transport
WX = Waiting for Sterling Connect:Direct Server
SUBmitter = (node name, user ID) | (list) specifies the nodeid and
user ID of the user that submitted the Process. Specify a list of
SUBmitter IDs by enclosing the IDs in parentheses and separating
them by commas.
CASE = Yes | No

ID, password, and data set name are case sensitive. The designation
refers only to the command, not the Process itself. See Indicating
Case Sensitivity for a general overview of case sensitivity. This
FILE | PRint | TABle
Specifies the form in which the information is presented. TABLE is

the default. See Indicating Output Destination for detailed
information about the output format produced by each of the these
parameters. This parameter is optional.
SELECT PROCESS Command Example

The following command searches for all Processes submitted by SMITH at the
node CD.DALLAS.
SEL PROC
96
WHERE (SUB=(CD.DALLAS, SMITH))
Issuing SELECT PROCESS through the Batch Interface

About this task
To use the SELECT PROCESS command from the Batch Interface, perform the
following steps:
Procedure
Issuing SELECT PROCESS through the IUI

About this task
Use the Select Process screen to specify the Processes that you want to display and
how you want them displayed. To issue the SELECT PROCESS command in the
Sterling Connect:Direct IUI, perform the following steps:
Procedure
1. Select option SP from the Primary Options Menu to display the Select Process
screen.
node.name
SELECT PROCESS
CMD ==> O
hh:mm
CMD:
O ... OPERATOR TABLE S ... OPERATOR TABLE/EXEC QUEUE STATUS
P ... PRINT REPORT
V ... VIEW PROCESS
QUEUE:
==> _ (A-ALL,W-WAIT,E-EXECUTE,H-HOLD,T-TIMER,P-PR)
==> ______
==> ______
==> ______
PROCESS NAMES:
==> ________
==> ________
==> ________
==> ________
SERVER NAMES:
==> ________
==> ________
==> ________
==> ________
STATUS:
(HO,HR,HI,HE,HC,HP,HS,PR,RH,RA,WC,WX,WT,H,R,W)
==> __
==> __
==> __
==> __
DESTINATION NODES:
==> ________________
==> ________________
==> ________________
==> ________________
USER ID:
NODE ID:
==> ________________________________________________________________
==> ________________
==> ________________________________________________________________
==> ________________
DO YOU WANT VALUES FOR THIS REQUEST TO BE CASE SENSITIVE? ==> NO
2. To select the Processes, specify the parameters to use as search criteria. These
parameters are described in SELECT PROCESS Command Format.
Note: The case sensitivity designation refers only to the command parameters
on the screen, not to the parameters of the Process itself.
3. To select the destination for your output, type the letter representing one of the
following output options on the command line:
v O accesses the Operator Table and creates a one line summary of each
selected PNODE Process. For more information, see Viewing and Controlling
a Process through the Operator Table.
97
v S builds an Operator Table consisting only of Processes that are currently

executing. The table shows how much data is transmitted for a COPY step.
For more information, see Accessing Execution Queue Status on the Operator
Table.
v V displays the content of the matching Processes within the TCQ. For more
information, see Viewing the Content of Processes Matching Your Search
Criteria.
v P prints a report of the selected Processes.
v D displays a report, similar to the following figure.
BROWSE -- temporary file name
----- LINE 00000000 COL 001 080
COMMAND ===>
SCROLL ===> PAGE
********************************* TOP OF DATA *******************************
===========================================================
SELECT PROCESS
===========================================================
Prc Name
=> PDEXCLUD
Queue
=> EXEC
Prc Num
=> 4
Status
=> EX
Prc Debug => 00003021
Subnode
=> SC.MVS.USERID
Time
=>
Other Node => SC.MVS.USERID
Date
=>
Server
=> SERVER1
Day
=>
Userid
=> USERID
Prty
=> 10
Retain => N
Ret proc => NONE
Class
=> 2
State
=> FILE I/O
Step Name => EXCLUDE
Xmit St =>
FUNCTION
=> COPY
MEMBER
=> V2SPEC
Sent: Blks => 371 Recs => 0 RUs => 1,075
___________________________________________________________
Prc Name
=> PDEXCLUD
Queue
=> EXEC
Prc Num
=> 4
Status
=> PR.CNTL
Viewing and Controlling a Process through the Operator Table

About this task
The Operator Table displays the PNODE Processes which satisfied your selection
criteria; it does not display information about Processes submitted from another
node.
Procedure
1. After you type O on the command line of the Select Process screen, the
Operator Table/Executing Queue screen is displayed.
The first two characters of the QUEUE indicate the queue, the second two
characters indicate the status value. The OTHER.NODE is the name of the
nonsubmitting node in the session.
2. Type an option in the OPTION column next to the Process name (PNAME) and
press Enter. The following table describes each option.
98
Option
Description
Place a nonexecuting Process on the Hold queue.
Delete a nonexecuting Process from the queue. For more information, see
Issuing the SUSPEND PROCESS, DELETE PROCESS, or FLUSH PROCESS
Commands through the IUI .
Release a held Process.
Suspend a Process from the executing queue. For more information, see Issuing
CHANGE PROCESS through the IUI .
Option
Description
Select a Process for detailed display. For more information, see Viewing and
Controlling a Process through the Selected Process Screen .
View a Process in the executing queue. For more information, see Viewing the
Content of Processes Matching Your Search Criteria .
Note: When you release a Process which contains RETAIN=YES, it is copied

and assigned a new Process number.
3. If you are required to confirm a delete or suspend Process request before it is
executed, respond to the Confirm Command prompt.
Note: If message ID SOPA006I is displayed on the Operator Table screen next
to the Process name under the OPTION column, it indicates that the Process
can no longer be found. The Process was probably in execute status when
another function was selected, and the screen was not refreshed. Screens are
not automatically refreshed. Press Enter to refresh the screen.
4. To view any message text, type END to leave the Operator Table and return to
the Select Process screen. Then type M on the command line, and press Enter.
Accessing Execution Queue Status on the Operator Table

Procedure
1. After you type S at the command line of the Select Process screen, the Operator
Table/Executing Queue displays Processes that are currently executing. The
Operator Table/ Executing Queue screen shows how much data is transmitted
by the COPY step, including:
v
v
v
v
v
v
Blocks for block-mode transmissions

Records for record-mode transmissions
RUs (request/response units)
I/O bytes
VTAM bytes
The compression factor
The following figure is a sample of the screen and shows that two Processes are
executing.
node.name
Row 1 to 2 of 2
-----------------------OPERATOR TABLE/EXECUTING QUEUE----------==> Q
SCROLL ===> PAGE
OPTION
PNAME
PNUMBER
SUBMITTER.NODE-- OTHER.NODE------ QUEUE
SERVER
USERID
------------------------------------------------------------------------------BENCHRC
272
Q1A.ZOS.V4600
Q1A.ZOS.V4600
P EX
S3
USER01
Blks
=> 6
Recs => 0
RUs => 173
I/O bytes => 177,138
Compression
VTAM bytes => 177,152
Factor => 0.0%
BENCHRC
272
Q1A.ZOS.V4600
Q1A.ZOS.V4600
EX EX
S3
USER01
Blks
=> 7
Recs => 0
RUs => 174
I/O bytes => 195,440
Compression
VTAM bytes => 178,176
Factor => 8.8%
******************************* Bottom of data ********************************
2. Type an option in the OPTION column next to the Process name (PNAME) and
press Enter. The following table describes each option.
99
Option
Description
Suspend a Process in the executing queue.
Select a Process for detailed display. For more information, see Viewing
and Controlling a Process through the Selected Process Screen .
Viewing and Controlling a Process through the Selected Process

Screen
About this task
To view and control a Process through the Selected Process Screen:
Procedure
1. From the Operator Table, type S in the OPTION column next to the name of
the Process to display the Selected Process screen. This screen displays details
about the Process that you selected from the Operator Table. The following
figure is a sample of the screen which displays all available information about
the particular Process you selected from the Operator Table.
node.name
SELECTED PROCESS
hh:mm
CMD ==> Select process command was successful.
Process Name
=> COPYCF
Number
=> 1
Step => COPYSTEP
Other Node
=> SC.IRV.TEST1
DEBUG => 00003001
Status =>EX
Commid
=> M3QRC763
Queue =>EXEC
Function
=> COPY
Sub State => SEND
State =>VTAM I/O
Server
=> SVTSERV1
PLEXCLASS => (
)
Submitter => SC.IRV.TEST1
SENDING SIDE
Userid
=> TEST1
Scheduled Time =>
Date
=>
Day
=>
Queueing Prty => 10
Class
=> 3
Retain => NO
Submitted Class=> NONE
Max Class => NONE
Sess.ID=> PNODE
Session restrt => 0
Dyn rstrt => 0
RouteID=>
Last Msgid
=>
Last RC
=> 00000000
RetProc=>
Secure=> UN-AUTHENTICATED
Signature => N Encryption=> NONE
Sending File
=> CDTEST1.TESTFILE.THRICE.V10
Receiving File => TEST1.TESTFL.THRICE
Volume seq no. => 1
Volser
=> USER01
TTRN
=> 00030200
Blks
=> 8
Recs
=> 2,486
RUs
=> 198
I/O bytes
=> 223,360
Member =>
VTAM bytes
=> 202,752
Compression Factor => 9.2%
2. Type any of the following Process control commands at the command line, and
press Enter. The following table describes each option:
Command
Description
Suspend the currently executing Process
Delete a nonexecuting Process
Place a nonexecuting Process in the HOLD queue
Release a nonexecuting Process
Enter
Monitor the currently executing Process execution
Change Other Node, Queueing Priority, Scheduled Time, Scheduled

Day, and Retain Status in a nonexecuting Process
3. To change parameters, move the cursor to the appropriate field on the screen,
make the changes that you want, and press Enter.
100
4. If you are required to confirm a Process request, respond to the Confirm

Delete/Suspend Command prompt.
5. If the Process completes execution while the Selected Process screen is
displayed, press Enter to return to the Operator Table screen.
Viewing the Content of Processes Matching Your Search Criteria

About this task
To view the content of Processes matching your search criteria:
Procedure
To view output on the VIEW PROCESS screen, do one of the following:
v Type a V on the command line on the Select Process screen after specifying the
parameters to use as search criteria. These parameters are described in SELECT
PROCESS Command Format. Also, for more information, see Issuing SELECT
PROCESS through the IUI.
v Type V in the OPTION column next to the Process name on the Operator
Table/Executing Queue screen. (The PNODE Processes which satisfied your
selection criteria on the Select Process screen are displayed on the Operator
Table/Executing Queue screen.) See Viewing and Controlling a Process through
the Selected Process Screen.
The following shows the sample output of the VIEW PROCESS command:
===========================================================
VIEW PROCESS
PROCESS NAME: TOEND
PROCESS NUMBER: 1
===========================================================
TOEND
PROCESS SNODE=CD.NODE
PNODE=CD.NODE
HOLD=YES
RETAIN=NO
CLASS=1
PRTY=2
STEP01
COPY FROM
(SNODE
DSN=USER01.JCL.LIB
DISP=(SHR)
)
TO
(PNODE
DSN=USER01.JCL.LIBX6
101
102
Chapter 8. Process Queuing and Recovery

Sterling Connect:Direct stores submitted Processes in the Transmission Control
Queue (TCQ). The TCQ controls Process execution. It consists of two
inter-dependent VSAM Relative Record Data Sets (RRDS), and an in-memory
queue which controls access. The two data sets are the TCQ and the TCX, which is
a space map for the TCQ.
Logical Queues
The TCQ has the following logical queues:
v Wait
v Execution
v Hold
v Timer
v Process Retention
Access the queues and manipulate Processes using the following Sterling
Connect:Direct commands:
v CHANGE PROCESS
v DELETE PROCESS
v FLUSH PROCESS
v SELECT PROCESS
v SUSPEND PROCESS
Refer to Controlling Processes with Commands, for more information the on each
of these Sterling Connect:Direct commands.
Queuing Parameters
The RETAIN, HOLD, and STARTT parameters queue Processes as described in
following table.
Parameters
Queue
Comments
None
Wait
Process remains on the Wait queue until Sterling

Connect:Direct can start a session with the SNODE. The
Process then moves to the Execution queue.
RETAIN=INITIAL
Hold
Process automatically executes each time Sterling

Connect:Direct is initialized with TCQ=WARM. This
setting is useful for Processes that contact other Sterling
Connect:Direct nodes each time Sterling Connect:Direct
completes initialization. This action causes any work
queued on the remote node for the local node to begin.
103
Parameters
Queue
Comments
RETAIN=YES
Hold
A copy of the Process is kept in the Hold queue after it

has executed. The Process does not execute again until it
is released by a CHANGE PROCESS command.
You can use RETAIN=YES, combined with STARTT, to
run a Process at a periodic interval. For example,
RETAIN=YES and STARTT=(Tuesday, 3pm) starts the
Process every Tuesday at 3 pm; RETAIN=YES and
STARTT=(,12:00) starts the Process each day at noon.
HOLD=YES
Hold
Process remains in the Hold queue until someone

releases the Process.
HOLD=CALL
Hold
Process is automatically moved from the Hold queue to

the Wait queue when the SNODE contacts the node on
which the Process resides.
STARTT
Timer
When the scheduled time and date arrive, the Process is

put on the wait queue and is available for execution.
You can use RETAIN=YES, combined with STARTT, to
run a Process at a periodic interval. For example,
RETAIN=YES and STARTT=(Tuesday, 3pm) starts the
Process every Tuesday at 3 pm; RETAIN=YES and
STARTT=(,12:00) starts the Process each day at noon.
You can also use the Timer queue for session retry and
file allocation retry based on Sterling Connect:Direct
initialization parameters specified by a particular
installation. When you exhaust retry limits, the Process
is moved to the Hold queue with an HE status.
When you submit a Process, Sterling Connect:Direct puts it in the appropriate

logical queue based on Process statement routing parameters listed in the
preceding table. See Process Execution Example for an illustration of how Sterling
Connect:Direct executes a Process.
TCQ Status and State Values

The SELECT PROCESS command displays Sterling Connect:Direct status values,
task state values, and transport state values. These are defined in the following
table:
104
Value
Definition
Sterling
Connect:Direct
Status Value
Each Process on the TCQ has an associated Sterling Connect:Direct status

value. This status value has a unique meaning determined by which
queue the Process is in. The SELECT PROCESS command displays
Sterling Connect:Direct status values.
Sterling
Connect:Direct
Task State
Values
When a Process is in the Execution queue, the SELECT PROCESS

command also displays a Sterling Connect:Direct task state value. The
state values are provided for information purposes. You cannot modify
or control them using Sterling Connect:Direct commands. The task state
value shows the current state of the Process. Usually, Sterling
Connect:Direct tasks are waiting for completion of a service such as File
I/O, Sterling Connect:Direct locked resource, or VTAM I/O.
Value
Definition
Transport State
Values
When a Process is on the Execution queue, the SELECT PROCESS

command can also display a transport state value, depending on timing.
The state values are provided for informational purposes. You cannot
modify or control them using Sterling Connect:Direct commands. For
example, if the Process is currently in a VTAM I/O state, the SELECT
PROCESS output can show a further state value such as send or receive.
While a Process is executing, the SELECT PROCESS command displays
the number of file blocks or records and VTAM request/response units
(RUs) sent or received. This display gives you an indication of the status
of COPY statements on the Process.
Wait Queue
The following table shows the Sterling Connect:Direct status value for the Wait
Queue:
Status Value
Explanation
WC
Waiting for Connection. This status is the initial queue status when a
Process is submitted without HOLD or RETAIN specified. This status
means the Process is ready to execute as soon as possible. Process is ready
to run but other Processes are executing with the same SNODE, and no
other sessions are available. This Process runs as soon as an eligible session
is available. If you find a Process in this state, it is most likely for this
reason. Processes are also in this state when Sterling Connect:Direct is
quiesced.
WT
Waiting for transport. This status is the status of a Process when the
transport protocol is not available. This Process runs as soon as the
transport protocol is available.
WX
Waiting for server. This status is the status of a Process waiting for a
Sterling Connect:Direct Server to become available. This Process runs as
soon as an eligible Sterling Connect:Direct Server is available. An eligible
Sterling Connect:Direct Server is an active server that supports the Process
PLEXCLASS and the transport protocol (SNA, TCP, UDT, or CTCA). The
transport protocol must also be available on the server for it to be eligible.
The following table shows the applicable commands for the Wait Queue:
Command
Description
Change Process
Modifies Process attributes
Delete Process
Removes the Process from the queue
Select Process
Displays Process status and state
Execution Queue
The following table shows the Sterling Connect:Direct status values for the
Execution Queue:
Status Value
Explanation
EX
Node is in Process control and executing the displayed Process.
WC (Waiting
Process control is in negotiation while the two nodes determine which
for Connection) Process executes next, based on priority.
105
Status Value
Explanation
PR.CNTL
This node is not in Process control. This status occurs: (1) during Process
negotiation where highest priority on either node runs next, or (2) when
the current node is the SNODE during Process execution.
SS
Session with other node is being started.
The following table shows Sterling Connect:Direct task state values for Processes in
the Execution Queue:
Task State
Explanation
DISPATCH
Task is waiting to dispatch
INACTIVE
Task can be dispatched but inactive
VTAM I/O
Task is waiting on VTAM request
P=SNODE
PNODE equals SNODE task
NETEX I/O
Waiting on NETEX I/O request
VSAM I/O
Waiting on VSAM I/O request
MISC
Miscellaneous I/O, such as a WTO
FILE I/O
Non-VSAM I/O
LOCK
Waiting for Sterling Connect:Direct locked resource
SUBTASK
Waiting on a subtask, such as open or close, allocation, security, or

RUN TASK
RUNNING
Executing instructions
TCA SCAN
TCA scan
TIMER
Waiting for timer event
ATTACH
Waiting for attached tape drive
ALLOCATE
Waiting for allocation to complete
MOUNT
Waiting for tape mount
OPEN
Waiting for OPEN to complete
The following table shows the Subtask state values for the Execution Queue. The
first characters of the subtask request state indicate the session protocol such as
TCP or LU6.2.
106
Subtask State
Explanation
ADOPT V2
Performing Adopt
CALL V2
Performing Call
INIT V2
Performing Initialization
CLEANUP
Performing Cleanup
HANGUP
Performing Hangup
SEND V2
Performing Send
SEND RSP
Performing Send Response
SEND SIG
Performing Send Signal
RECV V2
Performing Receive
ANSWER V2
Performing Answer
Subtask State
Explanation
IOCTL V2
Performing I/O Control
GET BUF
Performing I/O Control Get Buffer
RDY RCV
Performing I/O Control Ready Receive
The following table shows the transport state values for the Execution Queue:
Transport State
Explanation
NO SESSION
No VTAM session
SESSION EST
Session with another node being established
NO REQUEST
No VTAM request outstanding
RECEIVE
Waiting on VTAM RECEIVE request
OPEN
Waiting on VTAM OPEN request
CLOSE
Waiting on VTAM CLOSE request
SETLOGON
Waiting on VTAM SETLOGON request
REQSESS
Waiting on a request session request
OPNDST
Waiting on an open destination request
CLSDST
Waiting on a close destination request
GENCB EXTLST
Waiting on a GENCB EXLIST
GENCB ACB
Waiting on a GENCB ACB
GENCB NIB
Waiting on a GENCB NIB
GENCB RPL
Waiting on a GENCB RPL
REJSESS
Waiting on a reject session request
SESSIONC
Waiting on a session cancel request
INQUIRE
Waiting on an inquire request
OPNSEC
Waiting on an open secondary request
RSHUTD
Waiting on a request shutdown request
SIMLOGON
Waiting on a simulate logon request
SND RESPONSE
Waiting on a send response request
WAIT FOR +DR
Waiting on a definite response request
VTAM I/O
Waiting on VTAM request
SEND
Waiting on VTAM send request
DACTSESS
waiting on LU6.2 deactivate session request
RCVFMH5
Waiting on LU6.2 receive FMH-5 request
REJECT
Waiting on LU6.2 reject conversation request
ACTSESS
Waiting on LU6.2 activate session request
ALLOC ALLOCD Waiting on LU6.2 allocate conversation until available request
107
Transport State
Explanation
PRERECV
Waiting on LU6.2 prepare to receive request

Note: In a Sterling Connect:Direct/Plex environment, the LU6.2
connection protocol does not enable the Sterling Connect:Direct
Manager to redirect work to one of its servers. The remote node must
address the server on which you want to run an LU6.2 Process. To do
this, specify the node name and VTAM address of the Sterling
Connect:Direct Server on which the Process is to run in the remote
server's network map. Use the same CDPLEX.SERVER.NODE and
CDPLEX.VTAM specified for the local initialization parameters for the
Sterling Connect:Direct Server you are trying to address.
CNOS
Waiting on LU6.2 change number of session request
DELLOC
Waiting on LU6.2 deallocate conversation request
SEND
CONFRMD
Waiting on LU6.2 send confirmation request
6.2 RECEIVE
Waiting on LU6.2 receive request
6.2 SEND
Waiting on LU6.2 send request
SEND ERROR
Waiting on LU6.2 send error request
DISPLAY
Waiting on LU6.2 display session limit request
DEFINE
Waiting on LU6.2 define session limits request
ALLOC IMMED
Waiting on LU6.2 allocate conversation immediately request
The following table shows the allocate state values for the Execution Queue:
Allocate State Value
Explanation
SVC99
Performing SVC99
CAT SEARCH1
CAMLST locate
READ VTOC
CAMLST search
The following shows the applicable command descriptions for the Execution
Queue:
Applicable Command
Description
Flush Process
Terminates and deletes an executing Process
Select Process
Suspend Process
Terminates and moves an executing Process on the hold queue
Hold Queue
The following table shows the Sterling Connect:Direct Status values for the Hold
Queue:
108
Status Value
Explanation
HC (Held for Call)
Process is submitted with HOLD=CALL specified.

A session started from either node causes Sterling Connect:Direct
to place this Process on the wait queue in WC status, and
eventually in the execution queue (EX) when the first Process
finishes.
Note: If the SNODE is defined with a null IP address, the
Processes will be released serially. Refer to the HOLD parameter
in SUBMIT Command for more information.
HE (Held in Error)
The Process was submitted and received an error unrelated to

allocation or session errors. The Process is being checkpointed
and REQUEUE=YES is specified. A common error that causes
Sterling Connect:Direct to place the Process in HE status is an out
of space condition (Sx37 ABEND).
HI (Held Initially)
Process is submitted with HOLD=YES specified.
HO (Held by Operator)
An exception response is sent from the other node during FMH

exchanges at Process negotiation or step termination. It also
occurs if an FMH is invalid or is sent out of sync, or if the
remote node is not defined in the network map.
HP (Held due to
Process Error)
An exception response is sent from the other node during EXIT

exchanges at Process negotiation or step termination. HP also
occurs if an EXIT is invalid, sent out of sync, or if the remote
node is not defined in the Network map.
HR (Held Retain)
Process is submitted with RETAIN=YES specified or being held

for Process retry (intelligent retry).
HS (Held for
Suspension)
The operator issued a SUSPEND PROCess command. You can

release the Process later. The Process will run (Held for
Suspension) when Sterling Connect:Direct is recycled.
RA (Held for Restart

During Process execution, an allocation error occurred that
Due to Allocation Error) matched those specified in the initialization parameters. This
status enables the Process to restart after the allocation problem
is resolved.
RH (Restart Held)
Either the Process is being held awaiting a connection to an

inactive node by the Intelligent Session Retry feature (see
Intelligent Session Retry ) or a checkpointed Process is executing
when an error such as a lost session or an I/O error occurred.
This status enables the copy to restart when the session is
reestablished.
WC (Wait For
Connection)
Session establishment is attempted, including retries if specified,

and failed. The current Process is put on the wait queue (and
later EX Q) if a session with that node is established later. It also
can be released.
The following table shows the applicable commands for the Hold Queue:
Applicable Command
Description
Change Process
Delete Process
Select Process
109
Timer Queue
The following table shows the Sterling Connect:Direct Status values for the Timer
Queue:
Status Value
Explanation
RE (Retry)
The session with the SNODE is in the retry state. The number of
and interval between retries is specified in the initialization
parameters. The Process can be in retry status for session
establishment or for an allocation error.
WC (Wait For
Connection)
The Process is submitted with a start time or date (STARTT) that

has not expired. When the STARTT is reached, the Process is put on
the wait queue for scheduling to the EX Q.
The following table shows the applicable commands for the Timer Queue:
Applicable Command
Description
Change Process
Delete Process
Select Process
Process Recovery
Sterling Connect:Direct provides facilities to recover from most errors that occur
during Process execution. Recovery from the point of failure is usually
accomplished quickly. The following types of errors can occur during normal
operation:
v
v
v
v
Link failure terminates a session between Sterling Connect:Direct systems

File I/O error occurs during Process execution
Sterling Connect:Direct abends because of a hardware or other error
TCQ Corruption
Sterling Connect:Direct provides the following facilities to address errors:

Facility
Description
Session
establishment
retry
When one or more Processes run with a node, Sterling Connect:Direct

establishes a session with that node and begins execution. If Sterling
Connect:Direct cannot start the session, Sterling Connect:Direct retries the
session establishment. The initialization parameters, MAXRETRIES and
WTRETRIES, determine the number of retries and the interval between
retries.
If Sterling Connect:Direct cannot establish a session after all retries are
exhausted, the Process is placed in the Hold queue in the TCQ with a
status of Waiting for Connection (WC). When a session is established
with the other node, all other Processes are scanned and the highest
priority Process is executed after the previous Process is finished.
110
Facility
Description
VTAM
automatic
session retry
If Process execution is interrupted because of a VTAM session failure,

Sterling Connect:Direct automatically attempts to restart the session. This
recovery facility uses the same parameter values as the session
establishment retry facility.
If Sterling Connect:Direct cannot establish the session, the Process that is
executing and any other Processes that are ready to run with the other
node are placed in the Hold queue with a status of Waiting for
Connection (WC).
TCQ/TCX
Repair Utility
When the TCQ becomes corrupt because of an outage or other

circumstance, Sterling Connect:Direct may abend in production or during
the next DTF initialization. The Sterling Connect:Direct administrator can
use the TCQ/TCX repair utility to remove ambiguous or corrupt data
and avoid having to cold start the DTF and reinitialize the TCQ, thus
losing any Processes left in the TCQ.
Process step
checkpoint
As a Process executes, Sterling Connect:Direct records which step is

executing in the TCQ. If Process execution is interrupted for any reason,
the Process is held in the TCQ. When the Process is available for
execution again, Sterling Connect:Direct automatically begins execution
at that step.
COPY statement For physical sequential files and partitioned data sets, Sterling
checkpoint/
Connect:Direct collects positioning checkpoint information at specified
restart
intervals as a COPY statement executes. Checkpoints are taken for each
member that is transferred within a PDS, regardless of the checkpoint
interval. If the copying procedure is interrupted for any reason, you can
restart it at the last checkpoint position.
Note: Whenever a Process step is interrupted and restarted, some data
will be retransmitted. Statistics records for the Process step will reflect
the actual bytes transferred, and not the size of the file.
The COPY statement checkpoint/restart works in conjunction with step
restart. The restart is automatic if Sterling Connect:Direct can reestablish
a session based on the initialization parameter values for MAXRETRIES
and WTRETRIES. See COPY Statement Checkpoint/Restart Facility for
more information.
The CHANGE PROCESS command can also invoke the
checkpoint/restart facility. See Controlling Processes with Commands for
instructions on how to use the CHANGE PROCESS command.
Note: Checkpoint/restart is not supported for I/O exits at this time.
COPY Statement Checkpoint/Restart Facility

The checkpoint/restart facility includes the following elements:
v Initialization parameters
v Checkpoint/restart file
v Copy statement checkpoint parameters
Initialization Parameters
Sterling Connect:Direct uses the following initialization parameters with the COPY
statement checkpoint/restart facility:
111
Parameter
Description
CKPT.MODE
Specifies whether the checkpoint function is performed when Sterling

Connect:Direct is transferring a file in record mode or block mode.
(Record mode transfer is used when reblocking of the output file is
specified.) It also specifies whether the checkpoint function is
performed for partitioned data sets and if so, what type. Automatic
checkpointing of VSAM files is supported.
This parameter does not apply to TCP/IP and LU6.2 connections. With
TCP/IP and LU6.2 connections, checkpointing is based on the
checkpoint interval requested (regardless of the data set type or
whether it is in block or record format) and on both nodes' ability to
perform the checkpoint function. When both nodes agree to do
checkpointing, the checkpoint interval is controlled by the sending
node while checkpoint record filing is done on the receiving node.
CKPT
Specifies the default interval for checkpointing when it is not specified

on the COPY statement.
You should specify the CKPT value as a multiple of the value specified
for the V2.BUFSIZE initialization parameter. If you do not, performance
can seriously deteriorate.
Note: Be aware of additional overhead associated with specifying too
small a checkpoint interval, particularly when transferring large files.
Note: For sequential files, try to avoid using a CKPT value less than:
BLKSIZE * NCP * 10
where NCP is the number of buffers for reading data from
or writing data to a sequential data set using BSAM
For more information, search on Improving Performance in the IBM
CKPT.DAYS
Specifies the amount of time that checkpoint records are kept if they are
not deleted. Sterling Connect:Direct automatically deletes checkpoint
records when a Process is restarted and runs to a successful completion.
CKPTDSN
Specifies the name of the checkpoint/restart file that holds checkpoint

records during execution of the COPY statement.
For detailed information about these parameters, search on Global Initialization

Parameters in the IBM Sterling Connect:Direct for z/OS Administration Guide.
Checkpoint/Restart File
The Sterling Connect:Direct checkpoint/restart file contains positioning information
for both files involved in executing a COPY statement. Sterling Connect:Direct
maintains the checkpoint records throughout data transmission and deletes them
when a transmission completes successfully.
Note: Checkpoints take place on the receiving end of a transfer. During restart,
this information is exchanged with the sender so that appropriate positioning can
take place.
A checkpoint record can be left in the Checkpoint file if an interrupted Process is
deleted by the operator. Sterling Connect:Direct scans the checkpoint records
during initialization and deletes records older than the value specified in the
CKPT.DAYS initialization parameter.
112
COPY Statement Parameters

The CKPT and REQUEUE parameters of the COPY statement also control aspects
of the Checkpoint/Restart facility. The following table describes these parameters.
COPY statement parameters
Parameter
Description
CKPT
Specifies the interval Sterling Connect:Direct uses to record checkpoint

information. Sterling Connect:Direct uses this CKPT value, rounded to
the nearest block, in determining how many bytes to transfer before
taking a checkpoint.
If you do not specify the Copy statement CKPT parameter, Sterling
Connect:Direct uses the value specified in the CKPT initialization
parameter. Specifying a value of CKPT=0K, or not specifying CKPT in
the initialization parameters, disables checkpointing. Be aware of
additional overhead associated with specifying too small a checkpoint
interval, particularly when transferring large files.
REQUEUE
Indicates whether Sterling Connect:Direct requeues Processes that end

due to an ABEND, such as an Sx37, or enables any subsequent steps to
run to Process termination. This parameter is only effective if
checkpointing is in use. See the Connect:Direct Process Language help
for more information.
Checkpoint/Restart Examples for TCP/IP, UDT, or LU6.2

Transfers
The following examples describe how checkpoint/restart works for different
transfer types.
TCP/IP, UDT, or LU6.2 Transfers

In the case of transfers using TCP/IP or UDT, Sterling Connect:Direct sends
approximately 30 bytes of overhead after sending an amount of data equal to the
checkpoint interval in effect. Therefore, if the file size is 3 million bytes and the
checkpoint interval is 10k, then 30 bytes of overhead is sent 300 times, resulting in
a total overhead of 9000 bytes.
Other Transfers
For other transfers (LU0 or transfers to MS-DOS), Sterling Connect:Direct sends an
additional seven bytes per block or ten bytes per record of overhead during data
transfer. Data is sent in record mode when reblocking is taking place during
transfer (source and destination block sizes differ). When no reblocking is taking
place, Sterling Connect:Direct sends in block mode.
When you enable checkpointing, Sterling Connect:Direct transfers positioning
information in addition to the file. The positioning information enables Sterling
Connect:Direct to reposition the file in the event of an interruption. The following
examples show how to determine this overhead in number of bytes when using
Checkpoint/Restart for non-TCP/IP transfers.
In the following table, Sterling Connect:Direct checkpoints the file in block mode
and adds seven bytes to each block transmitted. This functionality adds only 2,100
bytes to the transmission of almost 6 million bytes.
113
File Attributes
Sending File
Receiving File
BLKSIZE
19,069
19,069
LRECL
DSORG
PS
PS
RECFM
FILE SIZE
300 blocks
300 blocks
In the following table, Sterling Connect:Direct checkpoints the file in record mode
because the data is being reblocked. Sterling Connect:Direct adds 10 bytes to each
record being transmitted. This functionality adds 150,000 bytes to the transmission,
or 5 percent overall.
File Attributes
Sending File
Receiving File
BLKSIZE
5,000
2,000
LRECL
200
200
DSORG
PS
PS
RECFM
FB
FB
FILE SIZE
600 blocks
1,500 blocks
RUN TASK Checkpoint/Restart

Sterling Connect:Direct for z/OS also offers a checkpoint/restart feature with the
RUN TASK Process statement.
If a RUN TASK program is executing on the SNODE and a session failure occurs,
the PNODE recognizes the session failure and puts the Process in the Timer queue
for retry. The SNODE, however, is still running the RUN TASK program and is not
aware of the session failure until the program finishes. The checkpoint/restart
feature for RUN TASK ensures that when the Process restarts on the PNODE, the
RUN TASK program does not execute a second time on the SNODE.
RUN TASK Checkpoint Records

Sterling Connect:Direct always writes a checkpoint record on the node where the
RUN TASK program executes. The initial checkpoint record is written upon entry
to DGADRNT$, the module that handles the RUN TASK Process statement.
Sterling Connect:Direct updates the checkpoint record before attaching the program
that is to execute. When the RUN TASK program finishes, Sterling Connect:Direct
updates the checkpoint record again.
RUN TASK Restart

If a RUN TASK Process step restarts, the node where the program executes
attempts to find the checkpoint record in the checkpoint file. If the RUN TASK step
is still executing, the Process that is running for the restart of the step waits for the
RUN TASK program to finish the first task and then proceed to the next step of
the Process.
At Process restart for a RUN TASK step, if the program is still executing, you see
two Processes in the EX queue for the same Process step. The first Process is
executing the program. The second Process is waiting for the first Process to
complete. When the first Process completes, it determines that the session it was
114
running under is lost and posts the second Process. The second Process records
how the RUN TASK step that is still executing ended, and proceeds to the next
step in the Process.
Re-execution of the RUN TASK

The RUN TASK step does not execute again if it is determined at restart that the
RUN TASK step ended because it finished before the PNODE restarted the Process.
However, if the RUN TASK program did not complete and is not currently
running, then the RESTART parameter determines the restart of the Process.
Also, if at restart, Sterling Connect:Direct cannot find the checkpoint record and
the RUN TASK program is not executing, Sterling Connect:Direct is unable to
determine what action to take for the restart. If Sterling Connect:Direct cannot
determine what action to take for the restart, it uses the RESTART parameter. You
can code the RESTART parameter on the RUN TASK step or in the initialization
parameters.
Note: If you code the RESTART parameter on the RUN TASK step, it overrides the
initialization parameter. When you code RESTART=YES, Sterling Connect:Direct
executes the program again. When you code RESTART=NO, the Process skips the
RUN TASK step.
Search on Global Initialization Parameters in the IBM Sterling Connect:Direct for
z/OS Administration Guide for detailed information about the
RUNTASK.RESTART initialization parameter.
115
116
Chapter 9. Process Results and Statistics

The SELECT STATISTICS command is used to retrieve statistics records. Use this
command to see the results of a Process that has finished executing.
Note: The Sterling Connect:Direct Activity Reporting System (ARS) produces
detailed statistics reports.
You can also use the Sterling Connect:Direct Browser User Interface to perform
some Sterling Connect:Direct for z/OS procedures.
Statistics Log Records

Sterling Connect:Direct keeps a record of operations and activity in a Statistics Log
file. This file contains the following record types:
Record Type
Provides Statistics About
Process Submit
The submitted Process
Member Copy
Transmission of a PDS member
Copy
How the COPY statement completed
Process Duration
How the Process completed
Run Job
A job submitted to the z/OS internal reader (JES)
Run Task
A program attached to the Process as a subtask
Submit within Process
A Process that is submitted within another Process
InterConnect Option
Results
Processes created by the InterConnect Option
For a table of statistics record types, refer to Using Sterling Connect:Direct Exits
Statistics Records Content

The statistics records include the following information:
v In all records:
Record type or function
Date and Time of record logging
Process name and number
User ID
Other node (secondary or primary) involved in the Process
Start and stop time of the function
Highest or final completion code and message
Step label name, if one is specified
v In the Member Copy record, the input and output member names
v In the Process Submit and Submit Within records, the submitted PDS DSN and
member name
v In the Copy record:
The number of records or blocks read from or written to the file, and whether
the transfer was performed in block or record mode
117
The number of I/O bytes that were read or written from disk or tape
The number of VTAM bytes sent or received during the session, including
Sterling Connect:Direct and VTAM control information
The RUSIZE
The size displayed is not the actual RUSIZE used by the transfer but rather
the RUSIZE indicated by the LOGMODE. VTAM can negotiate for a smaller
RUSIZE.
The compression percentage
This percentage is calculated by evaluating the number of VTAM bytes and
the number of I/O bytes. If the number of VTAM bytes is less than or equal
to the number of I/O bytes, a positive compression percentage is calculated
as:
Compression Percentage = (1 {VTAM Bytes I/O Bytes} ) x 100
If the number of VTAM bytes is greater than the number of I/O bytes, a
negative compression is calculated as:
Compression Percentage = (1 {I/O Bytes VTAM Bytes} )x 100
The compression percentage values displayed in the Copy Termination record

differ depending on the file attributes specified. A negative compression
percentage means that more bytes are sent than are read from the file. This
includes Sterling Connect:Direct control information.
Elapsed Time Significance

Use the following table to interpret the elapsed time between the start and stop
times for the different record types:
Record Type
Interpretation
For Copy
Termination
The elapsed time includes file allocation on both nodes and the time
required to mount a tape, when required.
For Run Task or

Run Job
The elapsed time indicates the time it took to run the task or job
before control returned to Sterling Connect:Direct.
For Submit within

Process
The elapsed time indicates the time it took to submit the Process to
the TCQ.
For an ESF Process

Submit
The start time is when the submit was performed (the Process was
added to the TCQ). The stop time is when the Process was first
added to the Process queue.
InterConnect Option Records

The InterConnect Option (ICO) routes files from a Sterling Connect:Direct node to
a Sterling Connect:Enterprise node for distribution, distributes batches to a Direct
node, and provides notification of success or failure of the Process. The
InterConnect software copies the entire content of the SYSPRINT file of the Sterling
Connect:Enterprise batch utility, STOUTL, into the Sterling Connect:Direct Statistics
file.
This report from STOUTL is displayed as a block by Sterling Connect:Direct. The
InterConnect Option software imposes a limit of 500 lines for the report. These
reports are retrievable only through the SELECT STATISTICS command FILE
option for batch, and the DISPLAY option for the IUI. Search on Offline Utilities in
the IBM Sterling Connect:Enterprise for z/OS Users Guide for samples of the
output reports from the ADD and EXTRACT functions.
118
Additional statistics records related to the InterConnect Option are written to the
statistics facility. For a list of those statistics records, search on Using Sterling
Connect:Direct Exits in the IBM Sterling Connect:Direct for z/OS Administration
Guide.
Note: If you specify a statistics exit in the initialization parameters, the LF and RO
records are passed to the exit.
SELECT STATISTICS Command

Use the SELECT STATISTICS command to retrieve and examine statistic log
records. You can select records based on certain conditions and indicate if you
want the output displayed, printed, or saved in a file for later processing. See
information about the FILE subparameter in Indicating Output Destination for how
to save your output in a file for processing later.
SELECT STATISTICS Command Format

SELECT STATISTICS has the following format and parameters. The required
parameters and keywords are in bold print. Default values for parameters and
subparameters are underlined.
Label
Command
Parameters
(optional)
SELect STATistics
WHERE (CCODE = (condition,completion code

EXCLUDE = (MEMber | MCR) | (WTO) | (NOTWTO) | (list)
MSGID = ID | (list)
SERVER = server name
STARTT = ([date|day][,hh:mm:ssXM])
STOPT = ([date | day][,hh:mm:ssXM])
USER = name | (list)
SNODE = name | (list)
TYPE = ID | (list)
FNAME = dsname | (list) | *
CASE = YES | NO
ARCHDSN = dsname | (list))
FILE | PRint | TABle | SUMmary
The following table describes the SELECT STATISTICS command parameters:
119
Parameter
Description
WHERE
CCODE = (condition,completion code
EXCLUDE = (MEMber | MCR)
| (WTO) | (NOTWTO) | (list)
MSGID = ID | (list)
SERVER = server name
STARTT = ([date|day][,hh:mm:ssXM])
STOPT = ([date | day][,hh:mm:ssXM])
USER = name | (list) SNODE = name
| (list)
TYPE = ID | (list)
FNAME = dsname | (list) | *
CASE = YES | NO |
ARCHDSN = dsname | (list))
Specifies which statistics records to examine. This parameter is

required. The subparameters, such as PNAME, PNUMBER, and
STARTT, are optional, but you must include at least one
subparameter.
120
CCODE = (condition, completion code) specifies selection by

completion code.
condition specifies a relationship to the completion code given in
the subsequent positional parameter.
The options for specifying condition include:
GT for greater than
LT for less than
EQ for equal to
NE for not equal to
GE for greater than or equal to
LE for less than or equal to
Parameter
Description
completion specifies a decimal value ranging from 1 to 2,147,483,647
to allow for all completion codes that the RUN TASK statement can
pass. This last value represents a maximum 31-bit binary number.
For example, if CCODE = (EQ,12) is specified, records that have a
Comp Code of 0000000C are selected.
For another example, if CCODE = (GT,0) is specified, you see
statistics records in which the step completion code is greater than
zero, as long as the records also meet other specified criteria.
EXCLUDE = (MEMBer | MCR) | (WTO) | (NOTWTO) | (list)
specifies to exclude certain statistics from selection. Specify a list of
excluded options by enclosing them in parentheses and separating
them by a space or a comma. To select all statistics, omit the
EXCLUDE parameter from the SELECT STATISTICS command. The
TYPE parameter overrides the EXCLUDE specifications.
MEMBer | MCR specifies whether or not to exclude the PDS
member copy record for PDS copies on the statistics report.
WTO specifies that Sterling Connect:Direct write-to-operator (WTO)
messages are excluded from the SELECT STATISTICS command.
Dynamic allocation messages are represented as WTOs in the
statistics file.
NOTWTO specifies that only WTO records are displayed (exclude
everything that is NOT a WTO record).
MSGID = ID | (list) specifies selection by message ID. You can
specify a list of message IDs by enclosing them in parentheses. You
can use a generic specification in the MSGID parameter using an
asterisk (*) at the end of the ID. For example, if you specify SCPA*,
then MSGIDs with SCPA in the first four characters of the message
ID are selected.
PNAME = name | (list) specifies selection by Process name. You can
specify a list of Processes by enclosing them in parentheses. You can
use a generic specification in the PNAME parameter by using an
asterisk (*) at the end of the name. For example, if you specify
PNAME=TEST*, then records with TEST in the first four characters
of the Process name field are selected regardless of the contents of
the remaining characters. Records having TEST, TEST123, and
TESTX all satisfy this selection criterion.
PNUMber = number | (list) specifies selection by Process number.
You can specify a list of Processes by enclosing them in parentheses.
The range is 1199999.
SERVER = server name specifies the name of the Sterling
Connect:Direct member where the statistics are generated. The
server name is a 18 character name assigned to each Sterling
Connect:Direct Server through the CDPLEX.SERVER initialization
parameter. This parameter is required in a Sterling
Connect:Direct/Plex.
121
Parameter
Description
STARTT = ([date | day] [,hh:mm:ssXM]) specifies selection by
designated starting date and time. The date or day and time are
positional parameters. If you do not specify the date or day, precede
the time with a comma.
date specifies the date to execute the Process. You can specify the
day (dd), month (mm), and year (yy for 2-digit year and yyyy for
4-digit year). You can use periods or backslashes (/) to separate the
components of a date value. You can omit the separators only for
transfers between mainframe nodes. Use separators to guarantee
transfers between all platforms.You can use the following date
formats, according to which date order is specified in the
DATEFORM initialization parameter:
v DATEFORM=MDY specifies the date format as mm/dd/yy,
mm/dd/yyyy, mm.dd.yy, or mm.dd.yyyy
v DATEFORM=DMY specifies the date format as dd/mm/yy,
dd/mm/yyyy, dd.mm.yy, or dd.mm.yyyy
v DATEFORM=YMD specifies the date format as yy/mm/dd,
yyyy/mm/dd, yy.mm.dd, or yyyy.mm.dd
v DATEFORM=YDM specifies the date format as yy/dd/mm,
yyyy/dd/mm, yy.dd.mm, or yyyy.dd.mm
Valid Julian dates formats are yyddd, yyyyddd, yy/ddd, yyyy/ddd,
yy.ddd, or yyyy.ddd.
If you do not specify the DATEFORM parameter, Sterling
Connect:Direct for z/OS defaults to MDY date format.
day specifies the day of the week to select. Valid names include
MOnday, TUesday, WEdnesday, THursday, FRiday, SAturday, and
SUnday. You can also specify YESTER to search for statistics records
created yesterday or TODAY to
hh:mm:ssXM indicates the time of day in hours (hh), minutes (mm),
and seconds (ss) to select. Set XM to AM or PM. You can use the
24-hour clock or the 12-hour clock. If you use the 24-hour clock,
valid times are 00:00-24:00. If you use the 12-hour clock, 1:00 hours
are expressed as 1:00AM, and 13:00 hours are expressed as 1PM. If
you use neither AM or PM, Sterling Connect:Direct assumes the
24-hour clock. You do not have to specify minutes and seconds.
You can also specify NOON, which searches for the statistics records
at noon, or MIDNIGHT, which searches for the statistics records at
midnight. The time default is 00:00:00, the beginning of the day.
If you specify time of day but not date, the output shows the first
available entry in the statistics log for that time of day. Statistics
from all later times and dates are output up to and including the
stop time.
If you do not specify the STARTT parameter, the search criterion
consists of any time before the STOPT parameter.
122
Parameter
Description
STOPT = ([date | day] [,hh:mm:ssXM]) Specifies a search for
statistics records up to and including the designated date, day, and
time positional parameters. If you do not specify the date or day,
place a comma before the time.
The date and time formats are the same as the STARTT parameter.
The time default is 24:00:00, the end of the day.
If you specify time of day but not date, all statistics through the
most recent entry for that time of day are output.
If you do not specify the STOPT parameter, Sterling Connect:Direct
selects statistics through the present time.
USER = name | (list) limits the selected statistics records to those
that are written for users with the specified name. You can specify a
list of names by enclosing them in parentheses. Use generic
specifications by placing an asterisk (*) at the end of the name. For
example, if you specify USER = SYS$*, then records with SYS$in the
first four characters of the USER field are selected regardless of the
contents of the remaining characters. Records having SYS$BOB,
SYS$ADM, and SYS$0001 all satisfy this selection criterion. USER
names can be up to 64 characters in length and can contain
lowercase characters.
SNODE = name | (list) limits the selected statistics records to those
that are written for Processes where the specified node name acted
as SNODE. You can specify a list of names by enclosing them in
parentheses. Use generic specifications by placing an asterisk (*) at
the end of the name. For example, if you specify SNODE=DALLAS*,
then records with DALLAS in the first six characters of the SNODE
field are selected regardless of the contents of the remaining
characters. Records having DALLAS.PROD, DALLAS.TEST, and
DALLAS all satisfy this selection criterion. SNODE names can
contain lowercase characters.
Note: When the statistics record shows NODE=S (SNODE), the
PNODE and SNODE fields are switched in that Process' statistics
record. For example, when a Run Task is submitted for SNODE
processing, the RT statistics record created at the PNODE contains
NODE=P and the PNODE and SNODE fields are as expected. For
the same task, the RT statistics record created at the SNODE
contains NODE=S and the PNODE and SNODE fields are reversed
for that Process.
123
Parameter
Description
TYPE = ID | (list) | * specifies the statistics record types to select.
Every statistics record Sterling Connect:Direct generates has an
associated record-type identifier. Each identifier is two characters
long and indicates the event or function that generated the record.
The identifier also indicates the record format and contents. Use
TYPE= * to view all record types. The TYPE subparameter specifies
which record types to select, and overrides the EXCLUDE parameter.
When you do not specify a TYPE, the record types selected are
determined by the output option chosen, and can be affected by the
EXCLUDE subparameter. When you specify the PRINT or TABLE
output option, the types in the following table are selected. Specify
FILE for the output option to select all available types. Use the
EXCLUDE subparameter to exclude certain types that the output
option included.
For a list of statistics record type identifiers, search on Statistics
Records in the IBM Sterling Connect:Direct for z/OS Administration
Guide.
FNAME=dsname | (list) | * limits the selected statistics records to
those that contain the specified file name. The FNAME
subparameter is meaningful for the following record types:
CT Copy Termination
RJ Run Job
SD Start Sterling Connect:Direct
SW Submit within Process
The meaning of the file name within these records is unique for each
record type. For example, the Run Job record contains the file name
of the submitted JCL. Filenames can be up to 254 characters in
length and can contain lowercase characters.
CASE=YES | NO
Specifies whether lowercase or mixed-case data is permitted for the

USER, SNODE, and FNAME subparameters. The CASE
subparameter overrides the global CASE option defined at signon
for the purpose of the SELECT STATISTICS command.
YES folds the data in USER, SNODE, and FNAME to uppercase
regardless of the actual data specified.
NO preserves the actual case typed for the USER, SNODE, and
FNAME subparameters. The CASE defaults to the setting defined
within the session defaults if nothing is specified.
ARCHDSN=dsname | (list)
124
Specifies that Sterling Connect:Direct is to search the archived

statistics files named, instead of the statistics log currently in use by
the DTF. Archived statistics files store old statistics data that is no
longer active in the statistics log. See your system administrator for
information about the availability of archived statistics at your site,
and for the data set names you can specify with the ARCHDSN
subparameter. See SELECT STATISTICS Command Format for
information on archiving statistics.
Parameter
Description
FILE | PRint | TABle | SUMmary
Specifies the output format. Indicate only one. TABLE is the default.
See Indicating Output Destination for an explanation of the output
produced by the selection of the FILE, PRINT, and TABLE
parameters. The SUMMARY parameter produces a 3-line summary
per statistics record, similar to the example on Statistics Log Records.
The reports from Sterling Connect:Enterprise are retrievable only
through the FILE option for batch and the DISPLAY option for the
IUI.
Using SELECT STATISTICS through the Batch Interface

About this task
To use the SELECT STATISTICS command from the Batch Interface, perform the
following steps:
Procedure
SELECT STATISTICS Command Examples

The following command searches for statistics records based on start and stop date
and time, and excludes write-to-operator statistics messages.
SEL STAT WHERE ( EXCLUDE=(WTO) STARTT=(11/24/2003,06:45:00) STOPT=(11/25/2003,8AM) )
The following command searches for statistics records based on start and stop date
and time, and excludes write-to-operator and PDS member copy statistics records.
SEL STAT WHERE (EXCLUDE=(WTO,MEMB) STARTT=(11/21/2003,15:25:00) STOPT=(11/25/2003,15:30:00) )
The following command searches for statistics records based on Process name, and
start and stop date and time. It excludes write-to-operator statistics messages.
SEL STAT WHERE ( EXCLUDE=(WTO) PNAME=BILLING STARTT=(12/28/2003,06:00) STOPT=(12/28/2003,23:00) )
The following command searches for signon records for the user Mary.
125
SEL STAT WHERE (USER=MARY, TYPE=SI) TABLE
The following command searches are identical and both select only WTO records.
SEL STAT WHERE (TYPE=WO) TABLE
SEL STAT WHERE (EXCLUDE=(NOTWTO)) TABLE
The following command searches for statistics records based on Process start/stop
date and time that ran on a Sterling Connect:Direct Server named SERVER1.
SEL STAT WHERE ( SERVER=SERVER1 STARTT=(12/28/2003,06:00) STOPT=(12/28/2003,23:00) )
The following command searches for Process submission records for Processes in
which the SNODE is any node in Dallas, and prints the output. Assume that the
site administrator indicates that the November statistics records are contained in a
file pair whose key sequenced data set is named SYS.ARCH.STATS.M9611. For an
explanation of statistics file pairs, search on Administering Statistics in the IBM
SEL STAT WHERE ( TYPE=(PS,SW) SNODE=DALLAS* ARCHDSN=SYS.ARCH.STATS.M9611 ) PRINT
The following command searches for signon and signoff records that match todays
date and the User ID SEAN.
SEL STAT WHERE ( TYPE=(SI,SO) USER=SEAN STARTT=(TODAY) STOPT=(TODAY,24:00:00) ) TABLE
The following command searches for the message ID SCMG010I and all message
IDs that begin with SCPA.
SEL STAT WHERE ( MSGID=(SCMG010I, SCPA*) )
126
SELECT STATISTICS Sample Output

The following shows sample output from a SELECT STATISTICS command.
node.name
SELECT STATISTICS
mm.dd.yyyy
=================================================================================
________________________________________________________________________________
Function
=> PROCESS SUBMIT
Start Time => 15:21:11
Process Name => BENCHRC
Stop Time => 15:21:11
Process Num => 272
Comp Code => 00000000
Comp Msg
=> SSPA001I
Userid
=> USER01
Primary
=> node.name
Step Name =>
Submitted DSN=> USER01.CD.PROCESS(SUB1)
_________________________________________________________________________________
Function
=> COPY
Stop Time => 15:21:12
Process Num => 272
Comp Code => 00000000
Comp Msg
=> SCPA000I
Userid
=> USER01
Primary
=> node.name
Step Name => STEP1
Server
=> S3
PLEXCLASS => (
)
From ( Snode
Dsn=CSDQA1.TESTFILE.BENCH.M1)
recs => 0
blks => 36
I/O BYTES => 1,000,000
VTAM BYTES => 1,000,072
Cmpr Perc => 0.0%
Digital Signature enabled = No
VOL=SER=> SVUS06
To
( Pnode
Dsn=CSDQA1.FILETEST.BENCH01)
recs => 0
blks => 36
I/O BYTES => 1,000,000
VTAM BYTES => 1,000,072
Cmpr Perc => 0.0%
Merged Signature enabled = No
Merged Encryption enabled = No
VOL=SER=> SVUS02
________________________________________________________________________________
Function
=> Process Term
Stop Time => 15:27:30
Process Num => 277
Comp Code => 00000000
Server
=> S2
Comp Msg
=> SVTM100I
Userid
=> USER01
Secondary
=> node.name
________________________________________________________________________________
The following figure illustrates the commands for archiving statistics for a single
day using the Batch Interface. These commands archive the statistics from the
previous day into the preallocated data set of the API referenced by the DD
DMTMPDSN.
SIGNON
USERID=(USERID,PASSWORD) TMPDD=DMTMPDSN NETMAP=HLQ.CD.NETMAP

SELECT STAT WHERE (STARTT=(YESTERDAY,00:00:00) STOPT=(YESTERDAY,24:00:00)) FILE
SIGNOFF
Using SELECT STATISTICS through the IUI

You can use the Select Statistics screen to select, display, and print statistics
information from Sterling Connect:Direct activities.
127
About this task

To select, display, or print statistics information using the IUI:
Procedure
1. Select option SS from the Primary Options Menu to display the Select Statistics
screen.
node.name
SELECT STATISTICS
CMD ==> P
Session not active. Only submits are allowed under ESF.
CMD: S ... SUMMARY TABLE
P ... PRINT REPORT
PROCESS NUMBERS:
==> ______
==> ______
==> ______
==> ______
PROCESS NAMES:
==> ________
==> ________
==> ________
==> ________
START DATE
==> TODAY_____
( YYYY.MM.DD )
START TIME
==> __________
(HH:MM:SSXM)
STOP DATE
==> TODAY_____
( YYYY.MM.DD )
STOP TIME
==> __________
(HH:MM:SSXM)
CONDITION CODE:
==> __ ________
EXCLUDE ( MEMBER RECS ==> Y
WTO RECS ==> Y
^WTO RECS ==>
CHANGE EXTENDED OPTS: ==> N
2.
hh:mm
yyyy.mm.dd
yyyy.ddd
N )
To access the Select Statistics Extended Options screen, type Y in the CHANGE
EXTENDED OPTS field. On the command line, type the command for the
output format that you want. The following table describes each option:
Command
Description
Display the output on the screen.
Send the output to the printer.
View unformatted statistic records.
Display a two-line summary per statistics record on the screen. See the
Statistics Summary figure on Statistics Summary.
Note: The records from the InterConnect Option are only retrievable through
the DISPLAY option.
The following table lists the statistics record types, their corresponding record
type identifiers, and whether they display through the Display Report
command, or the Change Extended Opts field of the Select Statistics screen.
128
Record ID
Description
Display
Report
Change Extended
Options
CE
Copy I/O Start
CH
Change Process
CI
Copy Step Start
CS
Statistics Command
CT
Copy Termination
CX
Check Certificate Validity
DC
Directory Commands
DP
Delete Process
DT
Select Task
Y
D
Y
Y
Display
Report
Change Extended
Options
Record ID
Description
DU
Delete User
EI
Event Services Start Command
ET
Event Services Stop Command
EV
Event Services Command
FA
IGWFAMS Message
FI
Long File Name Record
FP
Flush Process
FS
Suspend Process
FT
Flush Task
GO
Process Modal - GOTO, ELSE, or EXIT

Statement
HW
High Concurrent Session Count
IA
Inquire Statistics
IB
Inquire Debug
ID
Inquire STATDIR
IF
Process Modal - IF Statement
IP
Inquire Initialization parameters
IT
Inquire SNMP Trap Table
IU
Insert User
IX
Inquire Sterling Connect:Direct/Plex
JI
Run Job Start
LF
ICO Log File Record
M2
Multiple Copy Record
MC
PDS Member Copy
NL
Process modal - EIF or PEND statement
NM
NETMAP Updated
PE
Sterling Connect:Direct/Plex Error Record
PI
PNODE Process Start
PR
Performance Measurement Record
PS
Process Submit
PT
PNODE Process Termination
PX
Sterling Connect:Direct/Plex Activity

(Leave or Join Sterling
Connect:Direct/Plex)
QE
Queue Change to EXEC Queue
QH
Queue Change to HOLD Queue
QP
Queue Change to Process Retention Queue D
QT
Queue Change to TIMER Queue
QW
Queue Change to WAIT Queue
RE
ICO Report Record
RF
Refresh/Update initialization parameters
129
Display
Report
Change Extended
Options
Record ID
Description
RJ
Run Job
RO
ICO Event Record
RT
Run Task
S2
Statistics Logging Statistics
SB
Session Begin
SC
Statistics Control Record
SD
Start Sterling Connect:Direct
SF
Statistics Format
SI
Signon
SN
Select Netmap
SO
Signoff
SP
Select Process
SS
Select Statistics
ST
Stop Sterling Connect:Direct
SU
Select User
SW
Submit within a Process
SY
SYSOPTS
TF
TCQ Threshold Full
TI
Run Task Start
TL
TCQ Threshold Low
TP
Throughput Record Statistics
TR
Trap Event Record
TS
Suspend Task
TW
TCQ Threshold Warning
UM
Update Network map
UU
Update User
VP
View Process
WO
WTO
WS
Select Stat Command
XO
Trace On/Off
ZI
SNODE Process Start
ZT
SNODE Process Terminated
Y
D
Y
Y
The following screen is displayed if you selected Y in the CHANGE

EXTENDED OPTS field.
130
node.name
SELECT STATISTICS EXTENDED OPTIONS
CMD===> ________________________________________________________________
hh:mm
yyyy.mm.dd
yyyy.ddd
RECORD
==> __
==> __
==> __
TYPES:
==> __
==> __
==> __
SNODE NAME:
==> ________________ MESSAGE ID:
==> ________
USER ID:
==> ________________________________________________________________
FILENAME:
==> ________________________________________________________________
SEARCH
==> ______________________________________________
ARCHIVED
==> ______________________________________________
DATASETS:
==> ______________________________________________
SERVER:
==> ________
DO YOU WANT THE VALUES OF THIS REQUEST TO BE CASE SENSITIVE? ==> N
See the SELECT STATISTICS parameters description on SELECT STATISTICS

Command for information on how to complete the fields, or press PF1 for
Help.
Statistics Summary
If you selected S to display a statistics summary, the following Statistics Summary
screen is displayed:
----------------------STATISTICS SUMMARY--------------==>
ROW 1 TO 3 OF 3
SCROLL ===> PAGE
----SUBMITTER NODE----OTHER.NODE-----
FUNCTION
PNAME
PNUMBER
USERID
MSGID
RTNCD
END DATE/TIME
P|SNODE
SERVER
-----------------------------------------------------------------------------------* RUN-TASK
TESTMBR2 5
SC.MVS.QA5A
AS400.CDQA62
RBELL1
SERVER1
ARTT003I 000000008 MM/DD/YY HH:MM:SS PNODE
S COPY
TESTMBR2 5
SC.MVS.QA5A
AS400.CDQA62
RBELL1
SERVER2
SCPA001I 000000000 MM/DD/YY HH:MM:SS PNODE
SUB-CMD
TESTMBR2 5
SC.MVS.QA5A
AS400.CDQA62
RBELL1
SERVER2
SSPA001I 000000000 MM/DD/YY HH:MM:SS PNODE
The first and second lines of each entry identify a Process by function, Process
name and number, submitter node, other node, and user ID. The third line is the
message ID, return code, ending date and time of that Process, and Sterling
Connect:Direct Server that the Process ran on.
An asterisk (*) before the Process name indicates a nonzero return-code. You can
type M next to the Process name to display a description of the message ID
associated with the Process. Type S next to the Process name to show the statistics
in detail, as in the following figure.
131
node.name
Connect:Direct (TM) MESSAGE DISPLAY
CMD ==>
MSGID ==> SVSL003I
MODULE ==> DMVSOPEN
Copy requested DISP=(,CATLG) to already cataloged dataset.
The PROCESS COPY step requested a DISP=(,CATLG) on the TO
clause of the COPY statement. The requested dataset already
exists as a cataloged dataset.
System Action. The PROCESS COPY step is terminated with a
completion code of 8.
Response: Either correct the COPY dataset or uncatalog the
existing dataset and re-submit the PROCESS.
hh:mm
Display Statistics
If you typed D to display the output on screen, it is formatted as shown in the
following example.
Note: The statistics display function supports 133 character records and horizontal
scrolling using the standard ISPF scrolling function keys.
====================================================================================
PLEX.JOE
SELECT STATISTICS
24.03.2003
====================================================================================
Function
=> COPY
Start Time
=> 13:00:54
Process Name => PRCDATIM
Stop Time
=> 13:00:55
Process Num => 13273
Comp Code
=> 00000000
Comp Msg
=> SCPA000I
Userid
=> CBENN1
Secondary
=> PLEX.TOM.TCP
Step Name
=> STEP2
Other addr
=> 10.20.129.38
Other port
=> 02038
V2 Buffer Size => 65,536
Negotiated V2 Buffer Size => 65,536
TCP Buffer Size Used => 131,072
***** CHECKPOINTED; Interval = 1,000
From ( Pnode
Dsn=CBENN1.V44.PDS)
recs => 0
blks => 2
I/O BYTES => 8,400
VTAM BYTES => 2,183
Cmpr Perc => 74.0%
CMPrlevel=1
WINdowsize=13
MEMlevel=4
VOL=SER=> USER19
To ( Snode
Dsn=CBENN1.FTST.PRCDATIM.D1030325.T130042)
recs => 0
blks => 2
I/O BYTES => 8,400
VTAM BYTES => 2,183
Cmpr Perc => 74.0%
Merged Signature enabled = No
Merged Encryption enabled = No
VOL=SER=> USER11
The following figure illustrates how output to the system console and messages in
response to console commands are formatted.
132
BROWSE -- SYS.USER01.NDMAPI
----- LINE 00000097 COL 001 080
COMMAND ===>
SCROLL ===> CSR
____________________________________________________________________________________________________
Function => RUN TASK (PNODE)
Process Name => HYTADD01
Stop Time => 15:51:39
Process Num => 261
Comp Code => 00000000
Server =>
Comp Msg => SRTA000I
Userid => USER01
SECONDARY => USER01.MVS60.N2
STEP NAME => MBA$CREL
15:51:39 SVTM052I MBA$CRELRUN TASK HYTADD01( 261) SNODE=USER01.MVS60.N2 (0
15:51:39 SDAA004I - LOCATE MSG=NO TSODSN=NO DSN=IOVER1.CMCDIO.PROFILES(SUBADD0
15:51:39 SDAC006I (LOCATE) - R15=0000, R0=0000, Function completed successfully.
15:51:40 SDAA004I - ALLOC TSODSN=NO,DD=NDM00017,RETURN=(DSORG,DEVTYPE),D
15:51:40 SDAB005I - ERR=0000, INFO=0000, DYNAMIC ALLOCATION COMPLETED SUCCESSFUL
15:51:40 SDAA004I - LOCATE MSG=NO TSODSN=NO DSN= USER01.STOUTL.SYSIN.T632272
====================================================================================
USER01.MVS60.N1 SELECT STATISTICS DATE : 10/24/2003
====================================================================================
15:51:40 SDAC006I (LOCATE) - R15=0000, R0=0000, Function completed successfully.
15:51:40 SDAA004I - ALLOC TSODSN=NO,DD=NDM00018,RETURN=(DSORG,DEVTYPE),D
15:51:41 SDAA004I - UNALLOC DD=NDM00017
Note: In a Sterling Connect:Direct/Plex, all write-to-operator (WTO) records

display the Sterling Connect:Direct Server name (or XCF.NAME for a Sterling
Connect:Direct Manager) before the time.
SELECT MESSAGE Command

The SELECT MESSAGE command enables you to display message details using
the message ID. The SELECT MESSAGE command has the following format and
associated parameters. The required parameters and keywords are in bold print.
Default values for parameters and subparameters are underlined
Label
Command
(optional)
Parameter
SELect MeSsaGe WHERE (ID|MSGID= message ID) [Short |
Long]
The following table describes the SELECT MESSAGE command parameters

Parameter
Description
WHERE
Specifies the 8-character message identification. You can specify a

generic message ID.
ID | MSGID = message
ID
[Short | Long]
Specifies to display the message text in short or long format. The

short format is the default.
The following screens show examples of the SELECT MESSAGE command.

To use SELECT MESSAGE with a specific ID:
SELECT MSG WHERE (MSGID=SCPA0001) LONG
To use SELECT MESSAGE with a generic ID:

133
SELECT MESSAGE WHERE (MSGID=SCPA*)
134
Chapter 10. The Network Map

Retrieving Records from the Network Map File
Use the SELECT NETMAP command to retrieve records from the network map file
for display or further processing. The network map file is maintained by your
system administrator.
Issuing the SELECT NETMAP Command from the IUI

About this task
Use the Select network map screen to select a Network map record.
Procedure
1. Select option NM from the Primary Options Menu to display the Select
Netmap or TCP Information screen.
node.name
SELECT NETMAP OR TCP INFORMATION
CMD ==>
NETMAP INFORMATION
NODE KEY(S): ==> ________________
==> ________________
==> ________________
==> ________________
==> ________________
==> ________________
==> ________________
==> ________________
TCP INFORMATION
ADDRESS:__________________________________________
NAME: ________________________________________________________________
OUTPUT DESTINATION ==> DIS (DIS-DISPLAY,PR-PRINT)
hh:mm
2. Type the selection criteria for the nodes you want to examine and press Enter.
To select all nodes, you can simply press Enter.
The following is an example of a network map showing two nodes: CD.PLX44
and CDSELECT.SCO.
135
BROWSE
SYS06097.T144239.RA000.USER01.NDMAPI.H02
Line 00000000 Col 001 080
Command ===>
Scroll ===> PAGE
********************************* Top of Data **********************************
===========================================================
SELECT NETWORK MAP
===========================================================
Node Name
: CD.PLX44
VTAM Applid
: M1CDD97G
Max Parsess : 10
Def Ses Class : 1
Session Type: SNA
Environment
:
Node Status : INTERNAL, SEND, RECEIVE
ALT.COMM
: (ALT.DIR=BALANCE
(ALT.ADDR=10.20.129.101,ALT.PORT=13641,
ALT.TYPE=TCP , ALT.USE.OUT=YES ))
CRC
: DEFAULT
Session Snode Max : 255
PlexClass
: (
,
) Use.Server.Node: No
___________________________________________________________
Node Name
: CDSELECT.SCO
TCP PORT
: 13640
TCP Address : 10.20.246.244
Max Parsess : 20
Def Ses Class : 2
Session Type: TCP
Environment
: UNIX
Source IP
: 10.20.201.2
Node Status : INTERNAL, SEND, RECEIVE
ALT.COMM
: (ALT.DIR=TOP
(ALT.ADDR=MVSLPARA.CSG.STERCOMM.COM,
ALT.PORT=01364,ALT.TYPE=TCP ,
SOURCEIP=10.20.202.22 ,
ALT.USE.OUT=YES ))
CRC
: DEFAULT
Session Snode Max : 255
Contact
: Joe Dowe
Phone
: (xxx) xxx-xxxxx
Description : Connect:Direct for z/OS XXXX Node
You can make generic requests by using an asterisk. For example, type an
asterisk (*) in the first node key field to select all nodes and D* to select only
those nodes that begin with D. See SELECT NETMAP Command Format or
press PF1 for Help.
Note: The TCP information fields are for creating the SELECT TCPXLAT
command described in the next section. Do not fill them in for the SELECT
NETMAP command.
Issuing the SELECT NETMAP Command from the Batch

Interface
Procedure
To use the SELECT NETMAP command from the Batch Interface, place your
commands in the DGADBATC job stream and submit the job while Sterling
Connect:Direct is running. The following command displays all network map
entries for node names that begin with SAN.
SIGNON
SEL NET WHERE (NODE=(SAN*))
SIGNOFF
In the following example, the only node name in the network map which begins
with SAN is the SANFRAN node. This report contains a long DNS record, which
you can define in the Adjacent Node Definition in the network map. For more
information on the Adjacent Node Definition, search on Maintaining the Network
Map in the IBM Sterling Connect:Direct for z/OS Administration Guide.
136
============================================================================
SELECT NETWORK MAP
============================================================================
NODE NAME
: SANFRAN
VTAM APPLID
: M1A66789
MAX PARSESS : 10
DEF SES CLASS : 1
SESSION TYPE: SNA
ENVIRONMENT
: OS390
NODE STATUS : INTERNAL, SEND, RECEIVE
LONG DNS
: REGIONAL.MANAGER.OFFICE.IN.THE.SAN.FRANCIS
CO.BAY.AREA.CALIFORNIA.USA
ALT.COMM
: (ALT.DIR=BALANCE
(ALT.ADDR=M1A66790,ALT.TYPE=SNA ,
ALT.USE.OUT=YES ))
CRC
: DEFAULT
SESSION SNODE MAX : 255
CONTACT
: JOE SMITH
PHONE
: 345-999-6999
DESCRIPTION : SANFRAN TO TOKYO NODES PATH, SECONDARY P
ATH TO OSAKA.
SELECT NETMAP Command Format

The SELECT NETMAP command uses the following format and parameters. The
required parameters are in bold print. Default values for parameters and
Label
Command
Parameters
(optional)
SELect NETMAP
WHERE (NODE = (node| generic |(list)))

PRint | DISplay
The following table describes SELECT NETMAP parameters:

Parameter
Description
WHERE (NODE =
(node | generic |
(list))
Specifies which network map node definitions you want to examine.

WHERE is the only required parameter for the SELECT NETMAP
command.
NODE=(node |generic | (list)) specifies the network map node
names that are selected. Specify a list of node names by enclosing
them in parentheses and separating each by a comma or a blank.
node specifies a node name. The node is a 116 character
alphanumeric string, with the first character alphabetic.
generic specifies a generic selection of node names. To specify node
names generically, type a 17 character alphanumeric string, with the
first character alphabetic, plus an asterisk (*). For instance, if your
network includes node names PHOENIX, SANDIEGO, SANFRAN,
and TUCSON, a specification of SAN* provides information about
the SANDIEGO and SANFRAN nodes. If you type only an asterisk
(*), Sterling Connect:Direct displays (or prints) all nodes that you are
authorized to use.
PRint | DISplay
Indicates the output format. Indicate only one.
Translating TCP/IP Host Names to Network Addresses

Use the SELECT TCPXLAT command to translate TCP/IP host names to network
addresses and TCP/IP addresses to host names.
137
Issuing the SELECT TCPXLAT Command from the IUI

The Select NETMAP or TCP Information screen issues the SELECT TCPXLAT
command or the SELECT NETMAP command depending on your request.
Procedure
1. Select option NM from the Primary Options Menu to display the Select
Netmap or TCP Information screen. (See Issuing the SELECT NETMAP
Command from the IUI to see a screen sample.)
2. Press Tab until you reach the TCP INFORMATION portion of the screen. See
the parameter descriptions in SELECT TCPXLAT Command Format or press
PF1 for Help.
v To translate a host address to a fully qualified host name, type the address in
dot notation form in the ADDRESS field.
v To translate a host name to a real TCP/IP address, type the host name in the
NAME field. You can also type an alias name in this field if the host name is
too long for the space provided.
The following output is displayed:
xx.abc.node111
RESOLVED TCP NAME/ADDRESS
CMD ==>
TCP name/address translation successful.
TCP ADDRESS : 111.222.333.444
FULLY QUALIFIED TCP HOST NAME:
qaoptsol.csg.stercomm.com
____________________________ $$$$ ________________________________
14:56
Issuing the SELECT TCPXLAT Command with the Batch

Interface
To use the SELECT TCPXLAT command from the Batch Interface, place your
Connect:Direct is running. Use the batch version of the SELECT TCPXLAT
command to make multiple requests for resolution. The maximum number of
requests is 10.
Procedure
To use the SELECT TCPXLAT command from the Batch Interface, place your
Connect:Direct is running. Use the batch version of the SELECT TCPXLAT
command to make multiple requests for resolution. The maximum number of
requests is 10.
The following command produces the TCP Name/Address Translation Report. The
first two names listed in the TRTCPNAM parameter are aliases, the third is an
actual host name.
SIGNON
SEL TCPXLAT WHERE (TRTCPNAM=(NAME1, NAME2, tcpip.host.name3))
SEL TCPXLAT WHERE (TRTCPADR=(123.456.78.999, 123.456.789.012))
SIGNOFF
The following report shows the resolution of name to address or address to name.
REQUEST is what is typed in the command.
138
=============================================================================
TCP Name/Address Translation Report
=============================================================================
REQUEST
: NAME1
Host Address
: NNN.NNN.NN.NNN..
HOST NAME
: tcpip.host.name1
REQUEST
: NAME2
*** TCP Name/Address could not be resolved ***
REQUEST
: tcpip.host.name3
Host Address
: NNN.NNN.NN.NNN..
HOST NAME
: tcpip.host.name3
=============================================================================
TCP Name/Address Translation Report
=============================================================================
REQUEST
: 123.456.78.999
Host Address
: 123.456.78.999,
HOST NAME
: tcpip.host.name4
REQUEST
: 123.456.789.012
Host Address
: 123.456.789.012,
HOST NAME
: tcpip.host.name5
SELECT TCPXLAT Command Format

The SELECT TCPXLAT command uses the following format and parameters. The
required parameter is in bold print. Default values for parameters and
Label
Command
Parameters
(optional)
SELect TCPXLAT
WHERE (TRTCPNAM = (tcpip.host.name | (list))

TRTCPADR = (tcp.net.adr | (list)))
PRint | DISplay
The following table describes the SELECT TCPXLAT command parameters:

Parameter
Description
WHERE
(TRTCPNAM =
(tcpip.host.name | (list))
TRTCPADR =
(tcp.net.adr | (list)) )
Specifies which TCP host name or network address resolution you

want to examine. This parameter is required. Provide one of the
following subparameters:
TRTCPNAM = (tcpip.host.name | (list)) specifies a translation from
host name or alias to a real address. Type this name in the standard
format with each of the qualifiers being from 1 to 64 alphanumeric
characters, with a maximum name length of 64 characters. Specify a
list of names by enclosing them in parentheses and separating each
by a comma or a blank.
TRTCPADR = (tcp.net.adr | (list)) specifies a translation from an IP
address to the host name for that network. Type this address in the
dotted format (nnn.nnn.nnn.nnn) with a maximum length of 15
characters including periods. Specify a list of addresses by enclosing
them in parentheses and separating each by a comma or a blank.
PRint | DISplay
Specifies where output is directed. Indicate only one. When you

submit this command through DGADBATC, use the PRINT
parameter only.
139
140
Chapter 11. Utility Programs

Sterling Connect:Direct provides several utility programs and one I/O exit that
facilitate your use of the software. You can perform the following functions using
these programs and the exit:
v Notify the user of Process success or failure using DGADTIFY and DGADTFY2
v Dynamically allocate data sets using DGADTDYN
v Place job stream in a wait status for a specified period of time and set return
codes indicating whether the batch step or RUN TASK completed successfully or
failed by using the DGADWAIT program. You can use DGADWAIT with the
MAXDELAY parameter in a submit command or PROCESS statement to
synchronize Processes submitted through the batch interface.
v Dynamically invoke AMS (Access Method Services) to perform VSAM utility
functions using DGADTAMS
v Resolve symbolic references using DGADTSUB and DGADGSUB
v Compress and decompress files stored in a ZLIB compressed format
(DGASACMP)
v Determine how many concurrent sessions are running during a specific time
period (DGADVITL)
v Interface with the IBM utility ADRDSSU, by using the Sterling Connect:Direct
I/O exit, DGADSIOX. The ADRDSSU program enables you to copy
SMS-compressed data without having to decompress the data and also provides
support for copying wildcard-named files.
v Replace existing FTP sessions within z/OS job streams with Sterling
Connect:Direct for z/OS Processes using Sterling Connect:Direct FTP+ for z/OS
(CDFTP).
User Notification Programs

Sterling Connect:Direct provides sample programs that notify the console operator
or IUI users about the success or failure of any Process step. The sample programs
are supplied in source statement form in the Sterling Connect:Direct SDGASAMP
library and in load module form in Sterling Connect:Direct SDGALINK. Use RUN
TASK and MODAL statements with the sample programs to notify users.
The messages sent are standard TRANSFER SUCCESSFUL or TRANSFER FAILED
status messages.
Operator Console Notify Program (DGADTIFY)

The operator console program, DGADTIFY, works with the RUN TASK statement
to notify the console operator of the success or failure of Processes by means of
Write to Operator (WTO) messages.
The program must have the following parameters passed to it:
Parameter
Description
CL4GOOD'
| CL4FAIL'
The first positional parameter tells the program the correct message to
output. Code the parameter as illustrated in the following example,
including the single quotes.
141
Parameter
Description
file name
The second positional parameter is the name of the file that is being copied.
The following example shows a Sterling Connect:Direct for z/OS Process using the
DGADTIFY program.
COPY1 PROCESS PNODE=CDA SNODE=CDB
STEP01
COPY FROM ( PNODE DSN=FILE1 DISP=SHR ) TO ( SNODE DSN=FILE2 DISP=SHR )
STEP02
IF (STEP01=0) THEN
NOTIFYG
RUN TASK (PGM=DGADTIFY, PARM=(CL4GOOD,FILE1)) PNODE
ELSE
NOTIFYF
RUN TASK (PGM=DGADTIFY, PARM=(CL4FAIL,FILE1)) PNODE
EIF
The DGADTIFY program is attached on the PNODE. A parameter list containing

the GOOD or FAIL message criteria and the FILE1 file name is passed to
DGADTIFY. If the COPY statement is successful, the first RUN TASK step executes
and you see the following message:
SNTB001I ** CONNECT:DIRECT SUCCESSFUL STEP COMPLETION **
FILE XFER BETWEEN - PLEX.JOE AND - PLEX.TOM
SUCCESSFUL
REQUESTOR=CTENN1
DSN=CD.OUTPUT.data set
If the COPY statement is unsuccessful, the second RUN TASK step executes and
you see the following messages:
SNTB002I ** Connect:Direct FAILED STEP COMPLETION **
******** Connect:Direct FILE TRANSFER FAILED *********
FILE XFER BETWEEN - PLEX.JOE AND - PLEX.TOM FAILED
REQUESTOR=CTENN1
DSN=CD.OUTPUT.data set
User Notify Program (DGADTFY2)

Use the sample program, DGADTFY2, in conjunction with the RUN TASK
statement to notify TSO users of various conditions. The program accepts a
variable length parameter list to broadcast notification messages to users.
Note: The TSO user ID must be in the same z/OS image as the DTF where the
DGADTFY2 RUN TASK is running.
The following table describes the parameters:
142
Parameter
Description
CL4GOOD' |
CL4FAIL'
This first positional parameter indicates the success or failure of the

Process step. Code the parameter as illustrated in the following
example, including the single quotes.
file name
This second positional parameter is the name of the file that is being
copied.
user ID | user ID
list
The last parameter or list of parameters contains the TSO user IDs to
notify. Separate the user IDs with a comma.
The following example demonstrates a Process using the DGADTFY2 program.

COPY PROCESS PNODE=CDA SNODE=CDB
STEP01COPY FROM (PNODE DSN=FILE1 DISP=SHR) TO (SNODE DSN=FILE2 DISP=RPL )
STEP02 IF (STEP01=0) THEN
NOTIFY1
RUN TASK (PGM=DGADTFY2,PARM=(CL4GOOD,FILE1,CDID1,CDID2))SNODE
ELSE
NOTIFY2
RUN TASK (PGM=DGADTFY2,PARM=(CL4FAIL,FILE1,CDID1,CDID2))PNODE
EIF
A GOOD value is relayed to the TSO users CDID1 and CDID2 on CDB in the
following message:
SNTA001I **Connect:Direct FILE TRANSFER SUCCESSFUL**
TRANSFER BETWEEN - CDA
AND
- CDB
DSN=FILE1
A FAIL value is relayed to the TSO users CDID1 and CDID2 on CDA in the
following message.
SNTA002I ****Connect:Direct FILE TRANSFER FAILED****
TRANSFER BETWEEN
- CDA
AND
- CDB
DSN=FILE1
Dynamic Allocation Program (DGADTDYN)

The dynamic allocation program, DGADTDYN, performs several useful status
checking and housekeeping functions in a Process. It is located in the Sterling
Connect:Direct SDGALINK.
When multiple actions are contained in the parameters, the completion code
returned is the highest completion code encountered.
DGADTDYN Parameters
The RUN TASK command invokes DGADTDYN with parameters that define
allocation actions to execute. The following rules apply to the syntax of the
parameters:
v Perform each allocation action with as many parameters as required.
143
v Separate each unique allocation action by a parameter containing a fullword of

minus one (F'-1').
v A leading blank on the first parameter is not required; however, you must
include a leading blank on all subsequent parameters. If you do not include a
leading blank, the program issues an RC=30 and an SRTA005I message for the
Process.
v Parameters must not extend past column 72, or they are not read.
The following table shows the available dynamic allocation functions:
Function
Description
ALLOC
Use the ALLOC function to allocate a file. The allocation request can contain
most job stream DD statement options, including DCB options applicable to
allocation. This function is the default.
UNALLOC
Use the UNALLOC function to unallocate a file.
CONCAT
Use the CONCAT function to concatenate two files.
DECONCAT Use the DECONCAT function to perform dynamic deconcatenation.

LOCATE
Use the LOCATE function to locate cataloged data sets.
Note: You cannot access HFS files using DGADTDYN.
DGADTDYN Sample Program Uses

The following examples demonstrate how you can use the functions of the
DGADTDYN program.
Example 1: Locate and Allocate a Data Set

The following example calls the program DGADTDYN using the LOCATE
parameter to determine if a cataloged file exists.
If the file does not exist, the program issues a nonzero return code and makes a
call to allocate the file through the ALLOC parameter.
PROC1 PROCESS SNODE=BOSTON
LOCATE
RUN TASK(PGM=DGADTDYN PARM=(CLOCATE DSN=XYZ.CUSTOMER.FILE))SNODE
IF (LOCATE NE 0) THEN
ALLOC
RUN TASK (PGM=DGADTDYN PARM=(CALLOC, C DSN=XYZ.CUSTOMER.FILE, C DISP=(NEW,CATLG), C VOL=SER=DCM009, C SPACE=(CYL,(1,1)), C DSNTYPE=EXTPREF, C DCB=(RECFM=FB,DSORG=PS,LRECL=80,BLKSIZE=3120), C UNIT=3380))SNODE
EIF
Example 2: Delete and Uncatalog a Data Set

The following example deletes and uncatalogs a data set.
The first function, ALLOC, allocates the data set specifying a current status of OLD
and a secondary (or normal step completion) disposition of DELETE, which deletes
the data set.
144
The second function, UNALLOC, unallocates the data set. Because of the
disposition (the data set is originally allocated with disposition DELETE), the data
set is uncataloged.
Use the F'-1' as a separator between allocation functions.
PROC2 PROCESS SNODE=BOSTON
DELETE RUN TASK(PGM = DGADTDYN PARM = (CALLOC DSN=XYZ.TEMP DISP=(OLD,DELETE) F-1 CUNALLOC DSN=XYZ.TEMP))
Example 3: Allocate and Concatenate Data Sets

The following example calls the program to allocate each data set through the
ALLOC parameter. Then it calls DGADTDYN again to do the concatenation
through the CONCAT parameter. The data set is concatenated under the first
DDNAME in the CONCAT list.
RTDYNCON PROCESS SNODE=BOSTON
ALLOC1 RUN TASK (PGM=DGADTDYN PARM=(CALLOC DSN=XYZ.TEMP DISP=SHR DD=OLD1)) PNODE
ALLOC2 RUN TASK (PGM=DGADTDYN PARM=(CALLOC DSN=XYZ.TEMP2 DISP=SHR DD=OLD2)) PNODE
CONCAT RUN TASK (PGM=DGADTDYN PARM=(CCONCAT DD=(OLD1,OLD2))) PNODE
Example 4: Deconcatenate and Unallocate Data Sets

The following example calls the program to deconcatenate by DDNAME using the
DECONCAT parameter. Then it calls DGADTDYN again to unallocate each data
set in the concatenation with the UNALLOC command.
RTDYNCON PROCESS SNODE=BOSTON
DECONCAT RUN TASK (PGM=DGADTDYN PARM=(CDECONCAT DD=(OLD1))) PNODE
UNALLO1 RUN TASK (PGM=DGADTDYN PARM=(CUNALLOC DD=OLD1)) PNODE
UNALLO2 RUN TASK (PGM=DGADTDYN PARM=(CUNALLOC DD=OLD2)) PNODE
Run Task Wait Program (DGADWAIT)

Use the DGADWAIT program as a batch step or a RUN TASK to place a job
stream in a wait status for a specified period of time and set return codes
indicating when the step or task completes. To synchronize Processes submitted
through the batch interface, use DGADWAIT with the MAXDELAY parameter in a
SUBMIT command or PROCESS statement. For more information, see Using the
MAXDELAY Keyword Parameter to Synchronize Submitted Processes. This
program is distributed via SDGASAMP and must be assembled and link-edited to
the Sterling Connect:Direct load library.
The following table describes the positional parameters. If you execute
DGADWAIT as a RUN TASK, enclose the parameters in quotes because of the
embedded commas, for example, PARM=('1,2').
145
Parameter
Description
VALUE1
The first positional parameter indicates the time to wait. The default is
0 or you can use a comma to omit.
For seconds, specify (S)xxxx. The maximum is 9999 seconds or about
2.7 hours.
For minutes, specify Mxxx. The maximum is 999 minutes or about 16.6
hours.
For hours, specify Hxx. The maximum is H99 or about 4.1 days.
You can also specify ABEND' and then use the actual user ABEND
code for the second positional parameter.
VALUE2
The second positional parameter specifies the return code to set. The
default is 0. The maximum is 4095.
'-' causes a -1 value (if executed as a batch step, IBM displays the return
code value as 4095).
VALUE3
The third positional parameter is only used to display diagnostics as

WTO (write-to-operator) messages. Specify 'DIAG' or leave blank. Any
other value is ignored.
The following examples show how to use DGADWAIT in a RUN TASK. In the first
example, the program waits for one second, and then sets the return code to 2.
DGADWAIT PROCESS SNODE=NODE.NAME &PRM=1,2
STEP01
RUN TASK (PGM=DGADWAIT PARM=(&PRM))
In this example, the program does not wait, but sets the return code to 8.
DGADWAIT PROCESS SNODE=NODE.NAME &PRM=0,8
STEP01 RUN TASK (PGM=DGADWAIT PARM=(&PRM))
VSAM AMS Interface Program (DGADTAMS)

The VSAM AMS interface program, DGADTAMS, dynamically invokes AMS to
perform VSAM utility functions. The program is located in the Sterling
Connect:Direct SDGALINK.
The highest completion code encountered in any AMS action is returned.
DGADTAMS Parameters
DGADTAMS is invoked by the RUN TASK Process statement with the following
parameters that define allocation and AMS actions to execute.
146
Parameter
Description
sysprint
output
parameters
The first positional parameter is special because it defines dynamic

allocation parameters for the AMS SYSPRINT output. This parameter can
allocate a spool file or a user file. The FREE and RETURN subparameters
are required.
Note: You must specify all of the sysprint output parameters on the same
line. They cannot be on separate lines.
The following example defines a CLASS A SYSOUT spool file.
C'FREE=CLOSE, RETURN=(DD) SYSOUT=A'
control
statement
parameters
You can use any valid input to the VSAM AMS program as input to
DGADTAMS, even multiple input parameters defining one or more AMS
actions. You must begin all VSAM control statement parameters with a
blank.
DGADTAMS Sample Program

The following figure shows a sample of DGADTAMS using the Define Cluster
AMS function. The ASM SYSPRINT output is routed to the existing user file
XYZ.OUTPUT.
VADC1 PROCESS SNODE=BOSTON
DEFINE RUN TASK (PGM=DGADTAMS,
PARM=(CFREE=CLOSE,RETURN=(DD),DISP=OLD,DSN=XYZ.OUTPUT,
C DELETE(VSAM.PAY.CHECKS) CLUSTER, C DEFINE CLUSTER
-,C (NAME(VSAM.PAY.CHECKS)
-,C RECORDS(1)
-,C VOLUMES(DCM009)
-,C OWNER(NDM)
-,C NONINDEXED
-,C RECORDSIZE(4089 4089)
-,C SHAREOPTIONS (2))
-,C DATA
-,C (CONTROLINTERVALSIZE(4096)
-,C NAME(VSAM.PAY.CHECKS.DATA))
-,C CATALOG(USER.UCAT))) SNODE
Symbolic Resolution Utilities (DGADTSUB and DGADGSUB)

The Sterling Connect:Direct utility programs, DGADTSUB and DGADGSUB,
enable you to submit jobs to the internal reader, much like RUN JOB. DGADTSUB
has the added capability of symbolic resolution into the job. The RUN TASK
statement invokes DGADTSUB or DGADGSUB, which allows you to substitute
variables in the parameter list.
The following table lists DGADTSUB and DGADGSUB parameters, and
DGADGSUB variables:
Parameter
Description
JCL source
The first parameter is an allocation string to point to the job to submit.

Code it without a ddname because DGADTSUB acquires one. Sterling
Connect:Direct uses this value, along with the DISP parameter, to
allocate the data set that contains the JCL.
147
Parameter
Description
Subsequent
Parameters
Subsequent parameters define resolutions for symbols used in the JCL

itself. For each parameter, the first position is the name of the symbol
found in the JCL and the second position is the value used. Separate
the first and second positions by an equal sign (=), one or more spaces,
or a comma. The value is terminated by the end of the parameter
string, or a comma or space not within a quoted string. A parameter
can also contain only a symbol name, in which case the value to
substitute into the job stream is a null string.
Note: To pass lowercase data to the DGADTSUB program, use
SYSOPTS in the RUN TASK statement.
Variables (for use %SRCDSN

with
COPY step executed
DGADGSUB)
%DSTDSN
COPY step executed
%PROCNAME
The resolved FROM' data set name from the last

in this Process
The resolved TO' data set name from the last
in this Process
The name of this Process
%PROCNUM
The number of this Process
Note: To use %SRCDSN or %DSTDSN, the RUN TASK must be run on
the PNODE. The values for the %SRCDSN and %DSTDSN variables are
not available when the RUN TASK is run on the SNODE.
The following figure is an example of RUN TASK using the DGADTSUB program.
RUN TASK
(PGM=DGADTSUB PARM=(DSN=dsname,DISP=SHR, JOB X21JOB, RPTNAME REPORT01, CLASS A, FILE X21.FILE )) PNODE
The job stream source that corresponds to this RUN TASK statement is displayed
in the following figure. The values requiring substitution are presented in bold
type.
//&JOB JOB (79502),&RPTNAME,PRTY=12,TIME=(1),CLASS=&CLASS,
// REGION=512K,MSGLEVEL=(1,1),MSGCLASS=X,NOTIFY=BSMITH1
//PRINT
EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN
DD DUMMY,DCB=BLKSIZE=80
//SYSUT1
DD DISP=SHR,
//
DSN=&FILE
//SYSUT2
DD SYSOUT=&CLASS,DCB=(&FILE)
The following figure shows the resulting job stream after substitution has taken
place. Sterling Connect:Direct replaces the variables that began with & with the
assigned values in the DGADTSUB parameter list.
148
//X21JOB JOB (79502),REPORT01,PRTY=12,TIME=(1),CLASS=A,

// REGION=512K,MSGLEVEL=(1,1),MSGCLASS=X,NOTIFY=BSMITH1
//PRINT
EXEC PGM=IEBGENER
//SYSPRINT
DD SYSOUT=*
//SYSIN
DD DUMMY,DCB=BLKSIZE=80
//SYSUT1
DD DISP=SHR,
//
DSN=X21.FILE
//SYSUT2
DD SYSOUT=A,DCB=(X21.FILE)
//*
Passing Variables Using DGADGSUB

You can use the DGADGSUB program, which substitutes variables in the
parameter list and then calls the DGADTSUB program to process the parameter list
further.
Note: DGADGSUB is not intended to concatenate variables, only to substitute
them. Variable concatenation is handled by the parser at PROCESS submit time.
DGADGSUB is intended to pass variables to JCL to be substituted into the job.
To do this, modify an existing RUN TASK statement that calls DGADTSUB to call
DGADGSUB, and add the variables you want to use in the parameter list.
The following figure is an example of RUN TASK using the DGADGSUB program.
STEP01 RUN TASK(PGM=DGADGSUB PARM=(DSN=DALLAS1.ZOS.SRCLIB(JCLTEST1),DISP=SHR, JOB &JOBNAME, SRC %SRCDSN, DST
%DSTDSN
, PROCNAME %PROCNAME, PROCNUM %PROCNUM , DSN DSNNAME)) PNODE
In this example, the following circumstances are in effect:

v The FROM' data set in the last COPY step before this RUN TASK is
DALLAS1.FILE
v The TO' data set in the last COPY step before this RUN TASK is
DALLAS1.TEST.GDG.G0006V00
v The name of the Process is 'TESTPR'
v The Process number is 29
v The &JOBNAME is XYZ
The DGADGSUB program makes the variable substitutions and calls the
DGADTSUB program with the following parameters:
PARM=(DSN=DALLAS1.ZOS.SRCLIB(JCLTEST1),DISP=SHR, JOB XYZ, SRC DALLAS1.FILE, DST
DALLAS1.TEST.GDG.G0006V00
, PROCNAME TESTPR, PROCNUM 00029 , DSN DSNNAME))
149
Wherever &JOB, &SRC, &DST, &PROCNAME, &PROCNUM, and &DSN are

found in DALLAS1.ZOS.SRCLIB(JCLTEST1), the corresponding values are
substituted. Once all the substitutions have been made, the resultant JCL is
submitted to JES.
Using Symbolic Variables

It can also be useful to specify the values to substitute as symbols rather than their
actual value. You can then use a single Process for multiple purposes.
The following figure is an example of DGADTSUB that symbolically substitutes
values into a z/OS job being submitted to the internal reader. Sterling
Connect:Direct supports any symbols that begin with an ampersand.
In the example, the second and subsequent parameters name the symbol, without
the &, and value that the symbol becomes in the submitted job stream. Sterling
Connect:Direct substitutes the value itself when the Process is submitted.
DGADTSUB PROC SNODE=CD.OS39040.N1 NOTIFY=USER01 &CLASS=A &DEST=LOCAL &JOB=JOB1SB &RPTNAME='''RPT NAME''' &FILE=X21.FILE &JCL=X21.CNTL(SUBSUB)
*
*
RUN TASK (PGM=DGADTSUB PARM=(DSN=dsname,DISP=SHR, FILE
&FILE, JOB
&JOB, CLASS
&CLASS, DEST
&DEST, RPTNAME
&RPTNAME, )) PNODE
Sterling Connect:Direct Exits and DGADTSUB

If your Sterling Connect:Direct system uses any of the standard exits (Security,
RUN JOB, or RUN TASK), DGADTSUB functions with any or all of them without
further modification. Both a RUN TASK and a RUN JOB exit are invoked by
DGADTSUB, and any processing that takes place is done when using DGADTSUB.
Error Output
DGADTSUB writes any internal error information to the data set specified on the
CDESTAE DD statement. Always include this DD statement in the Sterling
Connect:Direct startup job stream.
Return Codes
The following table describes the DGADTSUB return codes:
Return Code
Meanings
04
A job stream record is truncated after substitution. Symbolic substitution is

performed on columns 171 of the JCL record. Truncation is indicated
when substitution causes the data in columns 171 to expand beyond
column 71.
For non-JCL records, substitution is performed on columns 180. The most
common cause of this error is sequence numbers in data statements.
150
08
An error occurred parsing the parameters or the job stream source.

A symbol length is greater than 19.
A symbol name is absent in the parameter string.
12
No parameters are passed.

An I/O error occurred.
An input data set allocation parameter is not found.
The symbol table overflowed.
A file open error occurred.
An input record length is greater than 256.
A member locate error occurred.
Batch Compression Utility (DGASACMP)

DGASACMP is a batch utility that compresses and stores files in ZLIB-compressed
format. You can transfer these compressed files using a Sterling Connect:Direct
Process and store them on the remote node as compressed data. A user can execute
DGASACMP on the remote node to decompress the data and store it in the
original format. These files cannot be decompressed using any other utility.
Note: You can also decompress files using a Sterling Connect:Direct Process. Refer
to Automatic Decompression for more information.
DGASACMP supports physical sequential files (PS), KSDS, ESDS, and RRDS
VSAM files. DGASACMP cannot allocate VSAM files as DISP=(NEW,CATLG), so
you must pre-define the VSAM output file when decompressing a file that was
originally VSAM.
DGASACMP does not support PDS (or PDSE) files as PDS, but you can use
IEBCOPY to unload the PDS, then compress or decompress using DGASACMP.
DGASACMP Parameters
You can pass the following parameters to DGASACMP:
Parameter
Description
MODE= COMP | DECOMP
Specify COMP to compress an input file. Specify DECOMP

to decompress a compressed file.
REPORT=NORMAL |
DEBUG
Specify NORMAL to instruct DGASACMP to produce a

summary statistics report. This value is the default. Specify
DEBUG to instruct DGASACMP to produce a detailed
statistics report.
151
ZLIB=(CMP=1 | n, WIN=13
| nn, MEM=4 | n)
These three parameters change the settings of the extended

compression utility. CMP indicates the compression level.
Valid values are 19. The default value is 1. WIN indicates
the window size. Valid values are 915. The default value is
13. MEM indicates the memory. Valid values are 19. The
default value is 4.
Note: Changing these values can significantly impact
performance and CPU overhead. Before you change the
default values, see Testing the Effects of Changing Values
for Extended Compression Parameters .
DGASACMP Examples
The following sample JCL, found as member DGAXCMP in $CD.SDGASAMP,
compresses a physical sequential (PS) file and stores it as compressed data.
//CDCMP JOB (1004),BATCH COMPRESS,CLASS=N,MSGCLASS=X,
//
COND=(1,LT),REGION=0M
//*
//* ZLIB COMPRESS A FILE IN BATCH
//*
//COMP
EXEC PGM=DGASACMP,PARM=MODE=COMP
//STEPLIB
DD
//INPUT
DD
DISP=SHR,DSN=$CD.FILE1
//OUTPUT
DD
DSN=$CD.FILE1.COMP,DISP=(NEW,CATLG),
//
UNIT=SYSDA,SPACE=(TRK,(1500,300),RLSE),
//
DCB=(BLKSIZE=27920,RECFM=U,DSORG=PS)
//SYSOUT
DD
SYSOUT=*,DCB=(BLKSIZE=133)
//*
The following sample JCL, found as member DGAXDCMP in $CD.SDGASAMP,

decompresses a compressed file and stores it in the original format.
//CDDECMP JOB (1004),BATCH COMPRESS,CLASS=N,MSGCLASS=X,
//
COND=(1,LT),REGION=0M
//*
//* ZLIB DE-COMPRESS A FILE IN BATCH
//*
//DECOMP
EXEC PGM=DGASACMP,PARM=MODE=DECOMP
//STEPLIB
DD
//INPUT
DD
DSN=$CD.FILE1.COMP,DISP=SHR
//OUTPUT
DD
DSN=$CD.FILE1.NEW,DISP=(NEW,CATLG),
//
UNIT=SYSDA,SPACE=(TRK,(1500,300),RLSE),
//
DCB=(RECFM=FB,LRECL=80,BLKSIZE=27920)
//SYSOUT
DD
SYSOUT=*
//*
152
DGASACMP Output
The following screen shows sample output from DGASACMP.
SACO000I
SACO001I
SACO002I
SACO003I
SACO011I
SACO012I
SACO021I
SACO022I
SACO023I
SACO024I
SACO031I
SACO032I
SACO033I
SACO034I
SACO999I
DGASACMP started, GMT =2001.275 19:39:25.00

OS Parm: MODE=COMP,
Options in effect: MODE=COMP CMP= 1
WIN=
ZLIB Version=1.2.3
INPUT DSORG=PS
RECFM=FB
RECSZ=
80
OUTPUT DSORG=PS
RECFM=U
RECSZ= 27,920
Total Records Read
=
12,500
Total Records Written
=
5
Total Bytes Read
=
1,000,000
Total Bytes Written
=
124,584
Compression Percent
=
88%
Compression Ratio
=
8.0:1
TCB CPU Seconds
=
2.627
Elapsed Seconds
=
4.103
DGASACMP utility completed successfully
13
MEM= 4
REPORT=NORMAL
DSN=CD.TESTFILE.M1
DSN=CD.TESTFILE.M1.COMP
You can also invoke DGASACMP with the OUTPUT DD as DUMMY, indicating
that the summary report is produced, but the output data is not stored. You must
still provide the DCB attributes. The following screen shows an example.
//OUTPUT
//
DD DUMMY,
DCB=(BLKSIZE=27920,RECFM=U,DSORG=PS)
Testing the Effects of Changing Values for Extended

Compression Parameters
Before you change the default values of the extended compression parameters
when using the DGASACMP utility, search on Improving Performance in the IBM
Sterling Connect:Direct for z/OS Administration Guide and review the benchmark
figures showing different test results. You can also use this utility offline to
determine the benefits of changing the default values in a test environment before
actually using compression on live data in your production environment.
About this task

Although extended compression using ZLIB is available on a global basis using the
ECZ initialization parameters and on a Process basis using the EXT parameters in
the COPY statement, performing compression online consumes significant CPU
resources. The DGASACMP utility produces a report (see the sample report in
DGASACMP Output), which shows how much the data was read, written,
compressed, and how long it took to compress. Another report is produced when
you use DGASACMP to decompress data and restore it to its original format.
To use DGASACMP to test compression, follow this procedure:
Procedure
1. Prepare a file containing the typical type of data you transfer and the average
amount of data involved in a transfer.
2. Transfer the file without using compression and record the time it takes for the
transfer to complete.
153
3. To test the results of compressing and decompressing the file, run DGASACMP
three times on the test file using the following settings. After each compression
run, run DGASACMP to decompress the file. Keep the output reports for each
test to compare results.
v CMP=1,WIN=13,MEM=4 (the default settings)
v CMP=1,WIN=1,MEM=14)
v CMP=8,WIN=1,MEM=14)
4. To determine if it is worthwhile to use compression and what extended
compression parameter values are most beneficial for your environment,
examine the test results taking the following factors into consideration:
v Amount of CPU and elapsed time it takes to compress and decompress the
data
v Amount of time it takes to send the data
v Virtual memory space used to maintain the ZLIB internal control blocks
v Virtual memory space used to allocate the compression window or history
buffer
v Type of data being sent, including its compressibility
Automatic Decompression
As an alternative to storing the data as compressed data on the remote node, you
can decompress a file during Process execution. This functionality is available
between z/OS and any other platform that supports ZLIB compression.
To perform automatic decompression, specify PRECOMP=YES in the SYSOPTS
parameter in the FROM clause of the COPY statement. PRECOMP=YES indicates
that the FROM data set is precompressed and instructs Sterling Connect:Direct to
decompress the file as part of the Process. If you do not code SYSOPTS or set
PRECOMP to NO, the file is sent in compressed format and the receiver must run
DGASACMP with MODE=DECOMP.
Note: If you are decompressing a file using DGASACMP, you cannot allocate
VSAM files as DISP=(NEW,CATLG). You must predefine the VSAM output file.
The following sample Process, found as member DGAPMPPS in $CD.SDGAPROC,
instructs Sterling Connect:Direct to decompress a file that is compressed using
DGASACMP.
Note: Refer to the $CD.SDGASAMP data set for more sample Processes.
CDCOMPPS PROCESS SNODE=CD.OS390
STEP1 COPY
FROM (DSN=$CD.FILE1.COMP
DISP=(SHR)
SYSOPTS=PRECOMP=YES
PNODE)
TO (DSN=$CD.FILE1.NEW
DISP=(RPL)
SNODE)
Determine High-Water Mark for a Period (DGADVITL)

The program called DGADVITL reports how many concurrent sessions (Processes)
are running during the time period specified. Below is a sample RUN TASK that
executes as a PNODE=SNODE Process when submitted. This Process must be force
flushed to discontinue. The MCS console displays the number of sessions that ran
154
during the specified period, and the time and date the high water mark was
reached. These messages appear in the JESMSGLG segment of the Sterling
Connect:Direct SYSOUT.
/****************************************************************/
/* RUN TASK FOR HIGH WATER PROCESS NUMBER; PNODE=SNODE */ /***************
************************************************/
RTBB PROCESS SNODE=your.local.node
STEP1 RUN TASK (PGM=DGADVITL,PARM=(C60)) PNODE
The parameter, C, is the number of minutes desired in a measurement interval. The

interval, 60, is an appropriate value to use. Since the Process that does the
measuring runs as a PNODE=SNODE Process, the system adds a count of 2 to
whatever the highest number of Processes that were running concurrently during a
particular sample window. For example, if 6 other Processes were running
simultaneously at a given time during the sample window, the value in the
SVIT001I message will be '0008'. If no Processes were running during that sample
time, the measuring Process is not counted, so the value in the SVIT001I message
is '0000'.
Following is an example of the output of the DGADVITL program:
SVIT001I SESSION HIGH WATER MARK OF: 0003 REACHED AT: 10:15:46 ON: 02000173
ADRDSSU Interface Program (DGADSIOX I/O Exit)

The DGADSIOX I/O exit dynamically invokes the IBM ADRDSSU utility to enable
you to copy:
v SMS-COMPRESSED data without first uncompressing the data
v Wildcard-named files
Running Traces for the DMDSSIOX I/O Exit

The DGADSIOX I/O exit automatically logs information to //ADRIOXLG each
time the ADRDSSU program is invoked regardless of the DEBUG bit settings.
However, to log additional tracing information, use the setting, DEBUG=00008000
or DEBUG=04008000 in the DEBUG DDNames in the Sterling Connect:Direct
startup JCL to generate an I/O Buffer Trace or an I/O Buffer Trace combined with
a separate trace per task. DGADSIOX I/O exit information logs to Rnnnnnnn while
DSS exit information logs to Xnnnnnnn.
DGADSIOX I/O Exit Sample Processes

Three sample Processes are provided in the $CD.SDGAPROC library distributed
with Sterling Connect:Direct that you can use to prepare a Process to execute the
DGADSIOX I/O exit:
v DGAPIOX1, which copies the SMS-COMPRESSED data set,
KSTIC1.SMSTEST.DMDSSU.COMP.OUTLIST, from the PNODE to a data set of
the same name on the SNODE but renames the SNODE data set to
MWATL1.SMSTEST.DMDSSU3.** as part of the execution of the ADRDSSU
utility on the SNODE.
v DGAPIOX2, which is similar to the DGAPIOX1 process but uses symbolic
substitution to name the input data set.
v DGAPWILD, which is set up to copy wildcard-named files
155
DGADSIOX I/O exit limitations and security considerations

Checkpoint/restart is not supported when using DGADSIOX I/O exit for the
following reasons:
v I/O exits in general including do not support Checkpoint/restart
v The IBM ADRDSSU utility does not support Checkpoint/restart
v Control cards are allow for wild-carded input
In addition, the ADRDSSU utility does not support DUMP/RESTORE of z/OS
UNIX System Services user files such as PATH='/u/kstic1/abc.txt'. However,
ADRDSSU does support HFS files.
The DGADSIOX I/O Exit utility program invokes DFSMSdss to perform requested
functions by calling the ADRDSSU utility via the cross-memory application
interface, documented in DFSMSdss Storage Administration. This cross-memory
interface causes a DFSMSdss server address space to start under the ASPACE
name of DGADSIOX.
For HFS and ZFS type files, there are restrictions related to UNIX System Services
that may result in failures or hangs without proper security. Please refer to
DFSMSdss Storage Administration (Application programming interface,
Cross-memory application interface restrictions) for a description of the restrictions
and set up requirements related to HFS and ZFS files.
Sterling Connect:Direct FTP+ for z/OS (CDFTP)

IBM Sterling Connect:Direct FTP+ for z/OS is a component of Sterling
Connect:Direct for z/OS that provides a simple and dynamic migration path from
unmanaged FTP sessions within z/OS job streams to a managed environment
using Sterling Connect:Direct for z/OS with minimal change to the JCL.
Sterling Connect:Direct FTP+ for z/OS provides a simple, reliable, and secure way
to transfer files between a Sterling Connect:Direct for z/OS installation at a central
processing center and remote Sterling Connect:Direct sites. Sterling Connect:Direct
FTP+ for z/OS runs as the client and supports Sterling Connect:Direct for z/OS,
Sterling Connect:Direct for Microsoft Windows, and Sterling Connect:Direct for
UNIX as the remote system.
Components of Sterling Connect:Direct FTP+

The major components of Sterling Connect:Direct FTP+ are:
v Sterling Connect:Direct FTP+ ManagerStarts as a job stream or started task just
like a Sterling Connect:Direct/Plex Manager. It handles Sterling Connect:Direct
FTP+ Clients and is only a PNODE. It cannot be contacted by a remote Sterling
Connect:Direct to start a process, and it cannot be contacted by a non-Sterling
Connect:Direct FTP+ Client. (The sample JCL, DGAXFTPJ, is in
$CD.SDGASAMP.)
The Sterling Connect:Direct FTP+ Manager enables the TCP API and can be
contacted by the ISPF IUI, Sterling Control Center, the Sterling Connect:Direct
Browser User Interface, and the Sterling Connect:Direct JAI.
v Sterling Connect:Direct FTP+ ClientStarts a special case of a Sterling
Connect:Direct Server. It builds and submits a Process which is scheduled by the
Sterling Connect:Direct FTP+ Manager back to the Sterling Connect:Direct FTP+
Client using the server name for the PLEXCLASS. It is only a PNODE and
156
cannot be contacted by a remote Sterling Connect:Direct to start a Process. (The

sample JCL, DGAXFCLI, is in $CD.SDGASAMP.)
v Sterling Connect:Direct FTP+ Plug-inProvides support for FTP commands that
Sterling Connect:Direct does not support, such as CWD (change working
directory), MKDIR (make a directory), RMDIR (remove directory), DIR (obtain a
directory listing of files), and DELETE and MDELETE (deleting files).
When the JCL is changed to use Sterling Connect:Direct FTP+ for z/OS instead of
FTP, all of the supported FTP commands are interpreted into appropriate COPY or
RUNTASK and COPY steps and executed within the Sterling Connect:Direct FTP+
Client started in the user's address space.
Security Considerations for Sterling Connect:Direct FTP+

The Sterling Connect:Direct files, Sterling Connect:Direct Secure Plus parameter file
and Netmap, are accessed through the Sterling Connect:Direct FTP+ Manager
under its authority. The only Sterling Connect:Direct file that is accessed through
the Sterling Connect:Direct FTP+ Client is the Sterling Connect:Direct Message File.
All file accesses on the local system will be performed under the authority of the
job userid (normal MVS operation). All file accesses on the remote system will be
performed under the authority of the userid/password used for the SNODEID in
the Sterling Connect:Direct FTP+ for z/OS Process.
To use the Sterling Connect:Direct FTP+ Client to connect to a remote Sterling
Connect:Direct for z/OS system, the remote userid must have HFS file access on
the remote Sterling Connect:Direct for z/OS system if the temporary file written by
the plug-in on Sterling Connect:Direct for z/OS is an HFS file or if HFS files or
directories are to be accessed.
Configure Sterling Connect:Direct FTP+ for z/OS

Before you can use Sterling Connect:Direct FTP+, certain installation and
configuration tasks must be performed.
Complete the following tasks:
v Install Sterling Connect:Direct FTP+ Plug-in
v Create CDFTP Procedure on page 158
v Create JCL to Start the Sterling Connect:Direct FTP+ Manager on page 159
v Update Netmap for Remote Nodes on page 161
v Start Sterling Connect:Direct FTP+ Manager on page 161
Install Sterling Connect:Direct FTP+ Plug-in

The Sterling Connect:Direct FTP+ Plug-in must be installed on the Sterling
Connect:Direct nodes that Sterling Connect:Direct FTP+ for z/OS communicates
with. The Sterling Connect:Direct FTP+ Plug-in is already included in the Sterling
Connect:Direct for z/OS installation. If the remote node is a Sterling Connect:Direct
for UNIX or Sterling Connect:Direct for Microsoft Windows server, the Sterling
Connect:Direct FTP+ Plug-in must be deployed on the remote system. For Sterling
Connect:Direct FTP+ Plug-in installation instructions for Sterling Connect:Direct for
Microsoft Windows and Sterling Connect:Direct for UNIX, refer to the latest IBM
Sterling Connect:Direct FTP+ 1.2 Release Notes.
Note: Make a note of the fully-qualified installation directory of the plug-in
(unless the remote node is Sterling Connect:Direct for z/OS) and the fully qualified
name of the plug-in temporary file on the remote Sterling Connect:Direct server.
You need this information when you update the Netmap.
157
Create CDFTP Procedure

Build the CDFTP procedure and save it in your system's PROCLIB. The CDFTP
procedure is executed in your modified FTP JCL. The sample JCL, DGAXFTPP, is
in $CD.SDGASAMP.
The following is an example of a CDFTP procedure:
//CDFTP
PROC
//CDFTP
EXEC PGM=DMINIT,REGION=0M,
// PARM=USER1.INIT.SDGAPARM(GLOBINIT),CDFTP
//STDENV DD DUMMY
//SYSTCPT DD DISP=(,DELETE),DSN=&&RES,
//
SPACE=(CYL,(1,1)),DCB=(DSORG=PS,RECFM=FB,
//
LRECL=80,BLKSIZE=24000),UNIT=SYSDA
//NETRC DD DISP=SHR,DSN=USER1.OS390.SRCLIB(NETRC)
//SYSTCPD
DD DISP=SHR,DSN=SYS2.TCPIP.PARMS(TCPDATA2)
//STEPLIB DD DISP=SHR,DSN=USER1.CD5000.LOADLIB
//CDPLEX DD DISP=SHR,DSN=USER1.INIT.SDGAPARM(SERVER)
//CDESTAE
DD SYSOUT=*
//ESTAE
DD SYSOUT=*
//NDMLOG
DD SYSOUT=*
In this example, the Global initialization parameters file, GLOBINIT, and local
initial initialization parameters file, SERVER, contain normal initialization
parameters for starting a Sterling Connect:Direct/Plex Server. If
CDPLEX.SERVER= is specified in the local initialization parameters, it is ignored
and the JES jobname is used as the server name. The specification of CDFTP as the
first override parm after the specification of the location of the initialization
parameters file identifies this DTF as a Sterling Connect:Direct FTP+ Client.
The SYSTCPT DD is required so that the Resolver will write its trace information
into this file when a request to the Resolver, such as GETHOSTNAME, is issued.
Sterling Connect:Direct FTP+ reads this trace information to get the resolved
DATASETPREFIX from the Resolver to determine which FTP.DATA file to open
and process.
A z/OS FTP client gets its configuration data from the FTP.DATA file and uses the
following search order to find this file:
v DD card - //SYSFTPD
v Tsoprefix.FTP.DATA
v Tsoid.FTP.DATA
v /etc/ftp.data
v SYS1.TCPPARMS(FTPDATA)
v tcpip_hlq.FTP.DATA
Sterling Connect:Direct FTP+ Client will attempt to find the correct FTP.DATA file
using the following search order:
v DD card - //SYSFTPD
v
v
v
v
JobUserid.FTP.DATA
/etc/ftp.data
SYS1.TCPPARMS(FTPDATA)
tcpip_hlq.FTP.DATA
Note: /etc/ftp.data must not be File Format NA or it will be ignored.
158
Note: tcpip_hlq is determined from DATASETPREFIX in the RESOLVER trace

information written in the SYSTCPT DD. If DATASETPREFIX is not found, the
default is TCPIP".
If the FTP.DATA file is found, the following configuration parameters are honored
by Sterling Connect:Direct FTP+ Client:
v
v
v
v
PRIMARYused for CDFTP.TEMPFILE allocation

SECONDARYused for CDFTP.TEMPFILE allocation
SPACETYPEused for CDFTP.TEMPFILE allocation
KEYRINGused to override Sterling Connect:Direct Secure Plus keyring
Note: The FTP.DATA file is used by both z/OS FTP and Sterling Connect:Direct
FTP+. Use ;CDFTPKEYRING if Sterling Connect:Direct FTP+ should use a
different keyring than z/OS FTP.
v ;CDFTPKEYRING ;used for a Sterling Connect:Direct FTP+ specific override of
Sterling Connect:Direct Secure Plus Keyring
Note: Do not forget to put a semi-colon (;) in front of CDFTPKEYRING and a
space followed by a semi-colon ( ;) at the end of CDFTPKEYRING, which makes
this statement a comment to z/OS FTP, but will still be recognized by Sterling
Connect:Direct FTP+ and processed.
CDFTPKEYRING ;(or KEYRING if ;CDFTPKEYRING ; is not specified) will
override the Sterling Connect:Direct Secure Plus specification of the keyring only
if the Sterling Connect:Direct Secure Plus Parmfile was defined with a keyring. If
the Sterling Connect:Direct Secure Plus Parmfile is defined to use a key
database, the FTP.DATA specification is ignored with a message to OUTPUT. To
explicitly specify to use the Sterling Connect:Direct Secure Plus Parmfile
definitions (keyring or key database, and to avoid the message to OUTPUT),
code: ;CDFTPKEYRING ;.
v SECURE_DATACONNused as default for Sterling Connect:Direct Secure Plus
transfers
The Sterling Connect:Direct FTP+ Client is a special case of a Sterling
Connect:Direct/Plex Server in a Sterling Connect:Direct/Plex environment. The
local initialization parameters file, SERVER, should specify:
CDPLEX.MANAGER=NO
For more information about global and local initialization parameters, see
Initialization Parameters in the IBM Sterling Connect:Direct for z/OS Administration
Guide.
Create JCL to Start the Sterling Connect:Direct FTP+ Manager

Create JCL to start the Sterling Connect:Direct FTP+ Manager. Refer to the
following JCL as an example:
159
//CD$MGR
JOB (CDHOSTD),FTPUSER,PRTY=12,TIME=1440,CLASS=Q,
// REGION=0M,MSGLEVEL=(1,1),MSGCLASS=X,NOTIFY=&SYSUID
/*JOBPARM LINES=999999
//************************************************************
//*
*
//*
CONNECT:DIRECT (Connect:Direct for z/OS MANAGER)
*
//*
*
//************************************************************
// SET PGM=DMINIT,P=,
//
E=STAT.INIT=COLD,TCQ=COLD
//NDMITST EXEC PGM=&PGM,REGION=0M,
// PARM=&P.USER1.INIT.SDGAPARM(GLOBINIT),CDFTP,&E
//CDPLEX
DD DISP=SHR,DSN=USER1.INIT.SDGAPARM(CDFTPMGR)
//CDSVCDMP DD DUMMY
//STEPLIB
DD DSN=USER1.CD5000.LOADLIB,DISP=SHR
//DMPUBLIB DD DSN=USER1.PROCESS.LIB,DISP=SHR
//ESTAE
DD SYSOUT=*
//CDESTAE
DD SYSOUT=*
//NDMLOG
DD SYSOUT=*
In this example, the JCL that starts the Sterling Connect:Direct FTP+ Manager is
similar to JCL that starts the Sterling Connect:Direct/Plex Manager. The initparm
override PARM CDFTP as the first override parm after the location of the global
initialization parameters makes this a Sterling Connect:Direct FTP+ Manager.
The following local and global initialization parameters are forced with no
message:
v TCP=OES
v SNA=NO
v CTCA=NO
v UDT=NO
v SECURITY=OFF (Sterling Connect:Direct FTP+ Client only. The Security
parameter is allowed for the Sterling Connect:Direct FTP+ Manager)
v TCQ=COLD
v CONFIRM.COLD.START=NO
v TCP.FMH.TIMER=00:00:00
v TCP.RUNTASK.TIMER=00:00:00
v PROCESS.RETENTION=NO
If you specify any of the following Global Initialization Parameters, they are
ignored:
v TCP.LISTEN
v UDT33.LISTEN
v MAXPROCESS
v MAXPRIMARY
v MAXSECONDARY
The local initialization parameters file for the Sterling Connect:Direct FTP+
Manager, CDFTPMGR, should specify:
CDPLEX.MANAGER=YES
For more information about global and local initialization parameters, see
Initialization Parameters in the IBM Sterling Connect:Direct for z/OS Administration
Guide.
160
Update Netmap for Remote Nodes

Sterling Connect:Direct FTP+ for z/OS gets its configuration information about
remote systems it connects to from the Sterling Connect:Direct Netmap.
Configure the following parameters in your Sterling Connect:Direct for z/OS
Netmap for each remote system that Sterling Connect:Direct FTP+ for z/OS
connects to:
v CDFTP.PLUGIN=<fully qualified installation directory of the Sterling
Connect:Direct FTP+ Plug-in>
This parameter is not required when the Netmap entry defines a z/OS system.
v CDFTP.TEMPFILE=<fully qualified name of the Sterling Connect:Direct FTP+
temporary file>
The Sterling Connect:Direct FTP+ Plug-in creates a temporary file to store the
results of a directory command RUNTASK operation.
Note: If no variables are used in the CDFTP.TEMPFILE, Sterling Connect:Direct
FTP+ for z/OS appends the job userid and the ASID and CPUID to the
CDFTP.TEMPFILE parameter as a further specification of uniqueness.
Several variables are available for substitution in the CDFTP.TEMPFILE
specification. The following variables allow you to build an appropriate unique
temporary file as a z/OS file:
&userid;The remote userid (lower case)
&USERID;The remote userid (upper case)
&lusrid;The local userid padded to eight characters with '$'
&lcpuid;The first eight bytes of the local CPUID with "C" overlaying the first
byte
v &asid;The four character Address Space ID prefixed with "AS"
For example, you can specify CDFTP.TEMPFILE= with a variable ("&userid;").
Sterling Connect:Direct FTP+ for z/OS inserts the remote userid in place of the
&userid;. In the following example, the userid specified in the script or NETRC
file is user1.
v
v
v
v
CDFTP.TEMPFILE=/u/&userid;/cdftp/temp.file
CDFTP.TEMPFILE resolves to:

CDFTP.TEMPFILE=/u/user1/cdftp/temp.file
In the script or NETRC file, specify the userid in the case expected for the
substitution.
Start Sterling Connect:Direct FTP+ Manager

Start the Sterling Connect:Direct FTP+ Manager as a job stream or started task the
same way you start Sterling Connect:Direct/Plex Manager using the JCL created in
the previous step.
The Sterling Connect:Direct FTP+ Manager must be running before the Sterling
Connect:Direct FTP+ Client can successfully contact the Sterling Connect:Direct
FTP+ Manager to perform its work.
For more information, see the IBM Sterling Connect:Direct for z/OS Administration
Guide.
161
Modify FTP JCL

Use the following procedure to modify your FTP JCL to use Sterling
Connect:Direct FTP+:
Procedure
1. Change EXEC PGM=FTP to EXEC PROC=CDFTP.
2. Change the INPUT and OUTPUT DD statements and other step statements to
specify the procedure step name. For example, change //INPUT to
//CDFTP.INPUT and change //OUTPUT to //CDFTP.OUTPUT.
3. Change the first statement in the INPUT data stream to specify the remote
Sterling Connect:Direct node name instead of the machine name for the FTP
server.
The following is an example of JCL that executes the CDFTP procedure:
//CD$FTPJC JOB (CDHOSTD),-CDFTP+-,TIME=(1440),CLASS=Q,
// REGION=0M,MSGLEVEL=(1,1),MSGCLASS=X,NOTIFY=&SYSUID
/*JOBPARM LINES=999999
//LIBS JCLLIB ORDER=(USER1.OS390.SRCLIB)
//CDFTP EXEC PROC=CDFTP
//CDFTP.NETRC DD DISP=SHR,DSN=USER1.OS390.SRCLIB(NETRC)
//CDFTP.FTPTRACE DD SYSOUT=*
//CDFTP.OUTPUT DD SYSOUT=*
//CDFTP.INPUT DD *
MVSB (exit
ebcdic
cd /u/user3
delimit
mkdir cdftptestlib
cd cdftptestlib
lcd USER1.CDFTP.TESTLIB
delimit
bin
site sbdataconn=(IBM-037,ISO8859-1)
locsite sbdataconn=(IBM-037,ISO8859-1)
put CDFTPJC1
ebcdic
put CDFTPJC1 CDFTPJC2
dir
ls
mdelete CDFTPJC*
cdup
rmdir cdftptestlib
close
quit
//
You must provide the following information in the JCL:

v Remote hostIn this example, the hostname of the FTP server is changed to
specify the Sterling Connect:Direct node name, MVSB, that is in the Netmap.
If the DNS name or IP address used by FTP is the nodename in the Netmap,
no change is required. However, duplicating the entry in the Netmap and
giving it the IP address or the DNS name as the node name may cause
Netmap checking problems. In this case, the script should be changed to use
the Netmap entry node name.
The remote host statement can also specify (exit, as shown in this example,
or (exit=nn to specify that any error exits the script with a reason code
(default is RC=8).
The remote host statement can also specify (secure=off|ssl|tls to specify
security options.
162
If both exit and secure= are specified; only one open parenthesis can be
used. For example, MVSB (exit 16 secure=off.
v Remote userid and passwordIn this example, they are obtained from the
NETRC file. If the remote userid and password are not specified in the
NETRC file, they must be included in the FTP script after the remote host.
In the following sample excerpt of JCL that executes the CDFTP procedure,
the remote host is PROD.ZOS1, the remote userid is user1 and the password
is S1VX$25B:
...
//CDFTP.INPUT DD *
PROD.ZOS1
user1 S1VX$25B
cd /u/daily
...
You do not specify the use of Sterling Connect:Direct Secure Plus in the JCL. It
is determined by the initialization parameters and the Sterling Connect:Direct
Secure Plus parameter file definitions for the node named in the script.
To simplify matching up statistics in the remote node with Sterling
Connect:Direct FTP+ for z/OS, the PROCESS name is the jobname and the
process number is the jobid. The jobname is also used for the Sterling
Connect:Direct FTP+ Client server name when contacting the Sterling
Connect:Direct FTP+ Manager.
Note: Only the JCL interface is implemented. The ISPF interface (option 6;FTP)
is not supported.
New SDGAPARM and SDGASAMP Members

The Sterling Connect:Direct SDGAPARM and SDGASAMP contain Initialization
Parameters, JCL, and other samples that you can use and modify in your Sterling
Connect:Direct FTP+ environment.
Member
Description
Location
DGAIPGBL
Global Initialization Parameters
SDGAPARM
DGAIPMGR
Manager Local Parameters
SDGAPARM
DGAIPSVR
Server (FTP+ Client) Local Parameters
SDGAPARM
DGAXFTPJ
CD FTP+ Manager Startup JCL
SDGASAMP
DGAXFCLI
CD FTP+ Client JCL
SDGASAMP
DGAXFTPP
CDFTP PROC
SDGASAMP
DGAXNETC
Sample NETRC
SDGASAMP
DGAXFTPM
Sample NETMAP Entry
SDGASAMP
Supported FTP Commands

Sterling Connect:Direct FTP+ for z/OS separates the z/OS FTP commands into
three categories:
v Commands completely supported
v Commands partially supported
v Commands accepted, but ignored.
163
All commands are case insensitive and can be abbreviated as specified in the z/OS
FTP documentation.
Fully Supported FTP Commands

The following FTP commands are fully supported by Sterling Connect:Direct FTP+
for z/OS as described in the following:
Command
Description
APpend
Appends a data set on the local host to a file on the foreign host
BINary
Sets the transfer type to IMAGE
CD
Changes the working directory
CDUp
Changes to the parent of the current working directory
CLEar
Sets the protection level for data transfers to CLEAR
CLose
Disconnects from the foreign host
COMpress
Sets the data transfer mode to compressed mode
CWd
Changes the working directory (Synonymous with CD)
DELEte
Deletes a single file on the foreign host
DELImit
Displays the delimiter character between the file_name and file_type
DIr
Lists the directory entries for files on the foreign host

Note: Format is from Sterling Connect:Direct for z/OS Plug-in
EBcdic
Sets the transfer type to EBCDIC
Get
Copies a file from the foreign host to your local host

Note: "(REPLACE" supported
GLob
Toggles globbing (the expansion of metacharacters in file names) for the

MDelete, MGet, and MPut subcommands
LCd
Changes the working directory on the local host
LPwd
Displays the name of the active working directory on the local host
LS
Lists the names of files on the foreign host
MDelete
Deletes multiple files on the foreign host
MGet
Copies multiple files from the foreign host to the local host
Note: "(REPLACE" supported
MPut
Copies multiple files on the local host to the foreign host
PRIvate
Sets the protection level for data transfers to PRIVATE
PROtect CLEAR
PROTECT sets the protection level for data transfers on data

connections. CLEAR sets SECURE=(ENC=N) in COPY steps.
PROtect PRIVATE PROTECT sets the protection level for data transfers on data
connections. PRIVATE sets SECURE=(ENC=Y) in COPY steps.
164
PUt
Copies a file on the local host to the foreign host
PWd
Displays the name of the active working directory on the foreign host
QUIt
Leaves the FTP command environment
REName
Renames a file on the foreign host
RMdir
Removes a directory
SENDSite
Enables or disables automatic transmission of the SIte subcommand

Note: Used to determine whether to propagate DCB or use
SITE/LOCSITE
Partially Supported FTP Commands

The following FTP commands are supported by Sterling Connect:Direct FTP+ with
limitations described in the Notes:
Command
Description
Note
AScii
Sets the transfer type to

ASCII
Treated as EBCDIC
BIG5
Sets the transfer type to BIG5. Only to set DBCS= table in Sterling
BIG is the minimum
Connect:Direct
abbreviation for BIG5.
HAngeul

HANGEUL
Only to set DBCS= table in Sterling

Connect:Direct
JIS78kj

JIS78KJ

Connect:Direct
JIS83kj

JIS83KJ

Connect:Direct
Ksc5601

KSC5601

Connect:Direct
LMkdir
Create a directory on the local "(LIKE" ignored

host
LOCSIte
Specifies information that is

used by the local host to
provide service specific to
that host system
Ignores all but:

v BLOCKS
v BLKSIZE
v BLOCKSIZE
v CONDISP
v CYLINDERS
v DIRECTORY
v LRECL
v PRIMARY
v RECFM
v SECONDARY
v TRACKS
Errors out on:
v TRUNCATE
v WRAPRECORD
MKdir
Creates a directory on the

foreign host
"(LIKE" ignored
MOde
Specifies the mode or data

format of the transfer
MODE C honored as COMPRESS. All

others ignored.
Open
Opens a connection to a
foreign host
Port ignored
Pass
Supplies a password to the

foreign host
No :userdata or account_information
supported (ignored)
PROMpt
Toggles interactive prompting Toggles prompt switch

for MDelete, MGet, and MPut
commands
PROXy
Executes an FTP
subcommand on a secondary
control connection
Treated as OPEN statement
165
Command
Description
Note
PROTect SAFE
Sets SECURE=(ENC=Y) in
COPY step
Treated as PROTECT PRIVATE
QUOte
Sends an uninterpreted string Interprets command locally

of data
SAfe
Sets the protection level on

data transfers to safe
Treated as PRIVATE. Sets

SECURE=(ENC=Y) in the COPY step.
SChinese

SCHINESE

Connect:Direct
SIte
Sends information to the

Ignores all but:
foreign host using site-specific v BLOCKS
commands
v BLKSIZE
v BLOCKSIZE
v CYLINDERS
v DIRECTORY
v FILETYPE JES
v LRECL
v PDSTYPE
v PRIMARY
v RECFM
v TRACKS
Errors out on:
v TRUNCATE
v WRAPRECORD
SUnique
Toggles the storage methods
NAME/NONAME not supported

Used to set DISP=NEW or DISP=RPL
for output file
TChinese

TCHINESE

Connect:Direct
TYpe
Specifies the transfer type
Ignores all but:

v TYPE I = BINARY
v TYPE A = ASCII
v TYPE E = EBCDIC
v TYPE B 2 = EUCKANJI
v TYPE F = IBMKANJI
v TYPE B 5 = HANGEUL
v TYPE B 4 = JIS78KJ
v TYPE B 3 = JIS83KJ
v TYPE B 6 = KSC5601
v TYPE B 1 = SJISKANJI
v TYPE B = SJISKANJI
User
Identifies you to a foreign

host
No :userdata and account_information

supported (ignored)
FTP Commands Accepted, But Ignored

The following commands are recognized, accepted, and ignored by Sterling
Connect:Direct FTP+. These commands do not produce errors.
166
FTP commands that are not supported or recognized, are ignored with appropriate
messages. However, if Sterling Connect:Direct FTP+ is in exit mode (exit or exit=
specified in the remote host statement), these commands stop the script and
terminate the step. This is how z/OS FTP behaves.
(LOC)SITE subcommands that are not supported or recognized are ignored and
do not terminate the step, even in exit mode. The exceptions to this z/OS FTP
behavior are the (LOC)SITE WRAPRECORD and TRUNCATE subcommands. If
these subcommands are specified, they always terminate the script (RC=8 when
not in exit mode and with the user's return code when in exit mode).
v ?
v
v
v
v
v
v
v
v
!
ACCount
BLock
CCc
CProtect
DEBug
DUMP
EUCKANJI
v FEature
v FIle
v HElp
v
v
v
v
Ibmkanji
LANGuage
LOCSTat
NOop
v RECord
v REStart
v SENDPort
v
v
v
v
v
SJiskanji
SRestart
STAtus
STREam
STRucture
v SYstem
v TSO
v UCs2
v Verbose
167
168
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
169
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.
170
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 2013. Portions of this code are derived from IBM Corp. Sample Programs.
Copyright IBM Corp. 2013.
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
171
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.
172
Index
A
ACTSESS transport state 107
ADMIN option 17
Administrative Options Menu 15
ADOPT V2 subtask state 106
ALLOC ALLOCD transport state 107
ALLOC IMMED transport state 108
ALLOCATE task state 106
ANSWER V2 subtask state 106
API
signon 45
Application Program Interface
DGADCHLA program 25
introduction 25
Application Program Interface (API) 53
ARCHDSN parameter 124
ATTACH task state 106
AUTH option 17
Automatic Decompression 154
B
backslashes 3
batch commands 9
batch interface 9
sample job stream 10
Batch Interface
signoff 50
using SIGNON 45
using SWAP NODE 49
C
CALL V2 subtask state 106
CASE parameter 6
with CHANGE PROCESS 85
with DELETE PROCESS, FLUSH
PROCESS, and SUSPEND
PROCESS 91
with SELECT PROCESS 96
with SELECT STATISTICS 124
with SUBMIT 64
case sensitivity 6
Case sensitivity
CHANGE PROCESS command 85
DELETE PROCESS, FLUSH PROCESS,
and SUSPEND PROCESS 91
CASE SENSITIVITY parameter 73, 80
CAT SEARCH1 Allocate state 108
CDFTP 156
CF option 15, 72
CHANGE PROCESS command
batch interface 88
description 83
examples 88
format 84
IUI 89
parameters 84
Change Process screen 89
Changing an existing Process 75
CHECKPOINT parameter 79
Checkpoint/restart examples 113
Checkpoint/restart file 112
CKPT parameter 112
CKPT.DAYS parameter 112
CKPT.MODE parameter 112
CKPTDSN parameter 112
CLASS parameter 64, 85
CLEANUP subtask state 106
CLOSE transport state 107
CLSDST transport state 107
CNOS transport state 108
command
example 3
syntax 3
comments 3
concatenation 3
continuation marks 3
Copy File Menu 78
Copyfile - Receiving File screen 81
CP option 16, 89
Creating a Process with statement
models 76
D
DACTSESS transport state 107
DDNAMES 10
DEBUG parameter 64
CHANGE PROCESS 85
DEFINE transport state 108
DELETE PROCESS command
batch 92
description 90
examples 91
parameters 90
Delete session 48
Deleting a nonexecuting Process 100
delimiters 3
DELLOC transport state 108
DEST parameter
CHANGE PROCESS 85
Detail statistics 131
DF IUI option 76
DF option 16, 72
DGADBATC
EXEC parameters 11
processing rules 9
DGADBATC program 9
DGADCHLA
DGADBATC return codes 12
parameters 26
sample program 34
DGADCHLA program 25
DGADGSUB
passing variables 149
DGADSIOX
exit limitations 156
security considerations 156
DGADTIFY 141
DGADTSUB 147, 150
DGADTSUB (continued)
return codes 150
DGADWAIT 145
DISPATCH task state 106
DISPLAY parameter 7
Display statistics 132
DISPLAY transport state 108
DMMSGFIL ddname 10
DMNETMAP ddname 10
DMPRINT ddname 10
DMPUBLIB ddname 10
DP option 16
DSN parameter 63
E
Elapsed time determinination 118
End command 49
Errors 110
EXEC parameters 11
EXEC status value 105
Execution queue
commands 108
status 99
subtask state values 106
task state values 106
transport state values 107
Execution Queue 105
EXTAREA parameter 28
EXTMSG parameter 28
EXTRC parameter 28
EXTSTRLN parameter 28
F
FILE I/O task state 106
FILE parameter 7
SELECT PROCESS 96
SELECT STATISTICS 125
FLUSH PROCESS command
batch 92
description 90
examples 91
parameters 90
FORCE FLUSH parameter 90
FP option 16
G
GENCB ACB transport state 107
GENCB EXTLST transport state 107
GENCB NIB transport state 107
GENCB RPL transport state 107
Generating a COPY Process
using the IUI 77
GET BUF subtask state 107
173
HANGUP subtask state 106

HC status value 109
HE status value 109
HI status value 109
HO status value 109
HOLD parameter 54, 64, 104
CHANGE PROCESS 85
Hold queue
commands 109
status values 108
HP status value 109
HR status value 109
HS status value 109
native format 2
NDMCMDS ddname 10
NETEX I/O task state 106
NETMAP.REFRESH parameter 85
network map
in DGADBATC 10
Network Map
Select NETMAP or TCP Information
screen 135
NEWNAME parameter 65
NM option 16
NO REQUEST transport state 107
NO SESSION transport state 107
NODE parameter 84
Non-master session 50
NOTIFY parameter 65
I
INACTIVE task state 106
INIT V2 subtask state 106
INITIAL COMMAND field 39
Initialization parameters 112
INQUIRE transport state 107
Intelligent session retry 55
INVALKEY parameter 28
IOCTL V2 subtask state 107
IUI SUBMIT options
overview 71
K
keyword parameters
O
OPEN task state 106
OPEN transport state 107
Operator Table
commands 20
deleting a Process from 93
suspending a Process from 93
Operator Table screen 98
Operator Table/Executing Queue
screen 99
OPNDST transport state 107
OPNSEC transport state 107
output destination 7
output format 7
Q
Queues 53
Queuing parameters
quotation marks 3
106
RA status value 109

RCVFMH5 transport state 107
RDY RCV subtask state 107
RE value 110
READ VTOC Allocate state 108
RECEIVE transport state 107
RECV V2 subtask state 106
REJECT transport state 107
REJSESS transport state 107
RELEASE parameter 86
Releasing a Process from the hold
queue 100
REQSESS transport state 107
REQUEUE parameter 67
requirements 9
RESTART parameter 87
RETAIN parameter 54, 67, 103
CHANGE PROCESS 87
return codes
DGADBATC 12
RH status value 109
RSHUTD transport state 107
RUN TASK
completion codes 121
re-execution 115
restart procedure 114
user notification programs 141
with DGADTAMS 146
with DGADTDYN 143
with DGADTFY2 142
with DGADTIFY 141
with DGADTSUB 147
RUNNING task state 106
M
Master session 50
MAXDELAY parameter 12, 65
Message Display screen 23
Message Maintenance screen 22
Message Summary screen 24
Messages
ISPF/PDF 20
printing 22
Sterling Connect
Direct 21
viewing by Message ID 22
MISC task state 106
Monitoring executing Processes 100
MOUNT task state 106
MS option 17, 47
MSG option 16
Multiple session SIGNON command
IUI 47
usage 47
Multiple Session Signon screen 47
174
P
P=SNODE task state 106
PACCT parameter 66
parentheses 3
PLEXCLASS parameter 66, 86
PNAME parameter
CHANGE PROCESS 84
PNODE parameter 66
PNODEID parameter 66
PNUMBER parameter
CHANGE PROCESS 84
positional parameters 2
PR.CNTL status value 106
PRERECV transport state 108
Primary Options Menu 15
DF 75
DP 93
End 49
FP 93
MSG 22
NM 135, 138
PS 93
SD 39
SIGNOFF 49
SS 128
SUS 93
SW 48
WHO 39
X 49
PRINT parameter 7
SELECT NETMAP command
103
L
label 2
LOCK task state
Logical queues
TCQ 103
PRINT parameter (continued)

SELECT PROCESS 96
SELECT TCPXLAT command 139
PROC parameter 63
Process control commands 83, 100
Process execution
example 56
Overview 53
PROCESS NAME parameter 79
Process recovery 110
Process routing routines 54
Process step checkpoint 111
Processes
manipulating in TCQ 1
viewing content based on search
criteria 101
PRTY parameter 67, 86
PS option 16
Putting nonexecuting Processes in the
Hold Queue 100
137
S
SACCT parameter 67
SB option 16, 71
Screens
Change Process 89
Copy File Menu 78
Copyfile - Receiving File 81
Message Display 23
Message Maintenance 22
Message Summary 24
Multiple Session Signon 47
Operator Table 98
Operator Table/Executing Queue 99
Primary Options Menu 15
Select Process 100
Selected Process 100
Signon 38
Statistics Detail - Copy 131
Statistics Display 132
Statistics Summary 131
Submit Process 72
User Authorization 18
SD option 16, 39
Search criteria and Processes 101
Security at signon 37
SELECT MESSAGE command 133
SELECT NETMAP command
IUI 135
parameters 137
SELECT PROCESS command
accessing Operator Table 98
description 94
example 96
format 94
IUI 97
SELECT STATISTICS command
batch 125
examples 125
format 119
overview 119
parameters 119
sample output 127
Selected Process screen 100
selection criteria 7
SEND CONFRMD transport state 108
SEND ERROR transport state 108
SEND RSP subtask state 106
SEND SIG subtask state 106
SEND transport state 107
SEND V2 subtask state 106
SESSION EST transport state 107
Session establishment retry 110
SESSIONC transport state 107
SETLOGON transport state 107
Sign off session 48
SIGNOFF command
IUI 49
SIGNON
different nodes 50
multiple session, batch 47
SIMLOGON transport state 107
SND RESPONSE transport state 107
SNODE parameter 68
SNODEID parameter 68
SP option 16, 97
special characters 3
SPF option 17
SS option 16
SS status value 106
STARTT parameter
CHANGE PROCESS command 87
description 54
in Process queue 104
SUBMIT command 69, 70
Statement models 76
Statistics Detail - Copy screen 131
Statistics Display screen 132
Statistics records content 117
Statistics Summary screen 131
Status value 104
STEPLIB ddname 10
Sterling Connect
Direct FTP+ for z/OS
component 156
Direct/Plex
messages 22
Sterling Connect:Direct commands 1
listing 1
writing 2
Sterling Connect:Direct exits
DGADTSUB 150
Sterling Connect:Direct/Plex
Process management 60
STOUTL utility 118
SUBMIT command
description 62
parameters 63
Submit Process screen 72
SUBMITTER parameter 84
Submitting a Process
using the DF IUI option 76
using the IUI 71, 74
SUBTASK task state 106
Summary statistics 131
SUSPEND PROCESS command
batch 92
description 89
examples 91
parameters 90
Suspending executing Processes 100
SVC99 Allocate state 108
SW option 17
SWAP Node
using through the Batch Interface 49
SWAP NODE command 48
SWAP NODE through the IUI 48
Swap session 48
Symbolic resolution utility 147, 150
symbolic substitution 3
Symbolic substitution
example 70
Symbolic variables 150
synchronizing Processes 12
SYSIN ddname 10
SYSPRINT ddname 10
TCQ status and state values 104

TCQ/TCX Repair Utility 111
Terminating a master session 50
Terminating a non-master session 50
Terminating two sessions 50
Timer queue
commands 110
TIMER task state 106
Transport state values 105
U
UICB fields 29
User Authorization screen 18
User notification programs 141
Utility programs
CDFTP 156
DGADTIFY 141
DGADTSUB 147, 150
V
validating Process syntax from IUI
submit and validate 72
without submitting the Process 72
Validating Processes
options 72
VSAM
I/O task state 106
VTAM
automatic session retry 111
I/O task state 106
I/O transport state 107
W
WAIT FOR +DR transport state 107
Wait queue
commands 105
WC status value 105, 109
WC value 110
WHERE parameter 7, 120, 133
CHANGE PROCESS 84
DELETE PROCESS 91
FLUSH PROCESS 91
SELECT NETMAP command 137
SELECT TCPXLAT command 139
SUSPEND PROCESS 91
WHO option 17
WT status value 105
WX status value 105
X
X command
49
T
t_ZOS_Issue_SUSPEND_FLUSH_DEL_IUI
TABLE parameter 7
SELECT PROCESS 96
Task state values 104
TCA SCAN task state 106
92
Index
175
176

Product Number: 5655-X01
Printed in USA

CDZ OSUser

Uploaded by

Copyright:

Available Formats

CDZ OSUser

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

CDZ OSUser

Uploaded by

Copyright:

Available Formats

IBM Sterling Connect:Direct for z/OS

Last updated: 3 September 2014

IBM Sterling Connect:Direct for z/OS

Last updated: 3 September 2014

Chapter 2. The batch interface . . . . . 9

Chapter 3. The Interactive User

Chapter 4. The Application Program

Chapter 5. Managing Sessions . . . . 37

Signing On to Multiple Sessions . . . . .

Chapter 6. Building, Modifying, and

Chapter 7. Controlling Processes in the

SUSPEND, FLUSH, and DELETE Command

Chapter 9. Process Results and

Chapter 10. The Network Map . . . . 135

IBM Sterling Connect:Direct for z/OS: User Guide

Chapter 11. Utility Programs . . . . . 141

Chapter 8. Process Queuing and

Retrieving Records from the Network Map File .

Issuing the SELECT TCPXLAT Command from

Chapter 1. Introduction to Sterling Connect:Direct commands

Enables you to issue Sterling Connect:Direct commands with the

Provides easy-to-use command entry through fill-in-the-blank screens.

Modify a Process in the TCQ

Remove a Process from the TCQ

Delete a record from the Type file (both a user and

Delete a user from the Authorization file

Terminate an Executing Process (both a user and

Remove a task from the Execution queue

View information about Sterling Connect:Direct

Display SNMP Trap Table

Insert a record in the Type file (both a user and

Add a user to the Authorization file

Run diagnostics and modify initialization

Display message detail using message ID

Copyright IBM Corp. 1999, 2012

Display node from the network map file

Examine a Process in the TCQ

Examine records in the Statistics Log

Display Sterling Connect:Direct system tasks

Translate TCP/IP host names - addresses

Examine the records in the Type file (both a user

Examine user authorization (administrative task)

Connect to Sterling Connect:Direct DTF

Terminate a connection to the Sterling

Perform statistics functions (administrative task)

Stop Sterling Connect:Direct operation

Submit a Process for execution

Suspend Process execution

Swap to another Sterling Connect:Direct node

Update the network map file (administrative task)

Update a record in the Type file (both a user and

Change user privileges (administrative task)

Writing Sterling Connect:Direct commands

Parameters and Subparameters

The following table explains each command component:

You can optionally identify your Sterling Connect:Direct command

IBM Sterling Connect:Direct for z/OS: User Guide

The command itself specifies the Sterling Connect:Direct function

Parameters or subparameters specify further instructions for the

==> _ ==> _