IBM 4J User Manual

Sterling Connect:Direct for UNIX

User Guide

Ve r s i o n 4 .1



Sterling Connect:Direct for UNIX

User Guide

Ve r s i o n 4 .1



Note

Before using this information and the product it supports, read the information in “Notices” on page 83.

This edition applies to version 4.1 of IBM Sterling Connect:Direct for UNIX and to all subsequent releases and modifications until otherwise indicated in new editions.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Chapter 1. Controlling and Monitoring

Processes ..............1

Overview of the Command Line Interface ....1

Starting the CLI ............1

Stopping the CLI ............1

CLI Commands ............1

CLI Job Control ............3

CLI History Commands .........4

Overview of Sterling Connect:Direct Commands . 4

Submitting a Process...........6

Changing Process Parameters .......13

Deleting a Process from the TCQ ......15

Removing a Process from the Execution Queue 17

Stopping Sterling Connect:Direct ......18

Viewing a Process in the TCQ .......19

Monitoring Process Status in the TCQ ....22

Determining the Outcome of a Process ....26

Generating a Detailed Output Report for a

Process ...............32

Generating a Summary Report for a Process . . 33

Running System Diagnostics........33

Chapter 2. Process Queuing .....37

Overview of the Transmission Control Queue . . . 37

Scheduling Sterling Connect:Direct Activity....37

Progression of a Process Through the TCQ ....38

The Execution Queue ..........39

The Wait Queue ............40

The Timer Queue ...........41

The Hold Queue............41

Example—Precompress a Binary File .....51

Example—Decompress a Text File ......51

Examples—csdacomp Command Help ....52

Example—Decompress a File on the Remote

Node During the Copy Step ........52

Example—Send Precompressed File to z/OS and

Storing It as Precompressed ........52

Validate Configuration Files .........53

Configuration Reports ...........53

Generating a Configuration Report on the Base

Installation .............54

Generating a Configuration Report on Sterling

Connect:Direct Secure Plus for UNIX .....55

Generating a Configuration Report on Sterling

Connect:Direct for SWIFTNet for UNIX ....56

Chapter 4. Writing Custom Programs 59

Introduction to Writing Custom Programs ....59

Compiling Custom Programs ........59

Writing Custom C Programs.........61

Creating a Connection to Sterling Connect:Direct

Using ndmapi_connect() or ndmapi_connect_c() . 62

Terminating a Connection Using

ndmapi_disconnect() or ndmapi_disconnect_c() . 63

Receiving Responses Using ndmapi_recvresp() or

ndmapi_recvresp_c() ..........64

Sending a Command to Sterling Connect:Direct

Using ndmapi_sendcmd() or

ndmapi_sendcmd_c() ..........68

Writing Custom C++ Programs ........69

Chapter 3. Sterling Connect:Direct

Utilities ..............43

Introduction to Translation Tables .......43

Creating a Translation Table ........43

Compiling a Translation Table Using the ndmxlt

Utility ...............44

Example—Creating a Translation Table ....44

Example—Modifying a Model Translation Table 45 Using Translation During File Transfer

Operations .............45

Translation Table Error Messages ......46

Accessing Sterling Connect:Direct Messages . . . 46

Message File Content ..........46

Message File Record Format ........47

Displaying Message Text .........47

Precompressing/Decompressing Files Using the

Standalone Batch Compression Utility .....48

Special Considerations for Using the Standalone

Batch Compression Utility ........48

Using the Standalone Batch Compression Utility 49

Example—Precompress a Text File ......51

Example—Precompress a Text File With

Codepage Conversion ..........51

Chapter 5. Writing User Exits .....75

User Exit Programs............75

User Exit Functions............75

Initializing Communications with exit_child_init()

or exit_child_init_c() ..........76

Waiting for a Message Using recv_exit_msg() or

recv_exit_msg_c() ...........77

Passing a File Descriptor Using send_exit_file()

or send_exit_file_c() ..........77

Sending a Message to Sterling Connect:Direct Using send_exit_msg() or send_exit_msg_c() . . 78

Overview of User Exit Messages .......79

Statistics Exit Message..........79

File Open Exit Messages .........79

Security Exit Messages .........80

User Exit Stop Message .........82

Copy Control Block...........82

Exit Log Files..............82

Notices ..............83

Index ...............87

iv Sterling Connect:Direct for UNIX: User Guide

Chapter 1. Controlling and Monitoring Processes

Overview of the Command Line Interface

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

Starting the CLI

Procedure

1. If you have not defined the NDMAPICFG environment variable, type the

following command for the appropriate shell, where d_dir is the path to the Sterling Connect:Direct subdirectory.

In the C shell:

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

In the Bourne or Korn shell:

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

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

options as required:

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

Stopping the CLI

Procedure

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

CLI Commands

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

Option Description Value

-P Identifies the custom string to use at the command line prompt.

If the prompt string includes spaces or special characters, enclose it in single or double quotation marks.

The prompt string can also be specified in the ndmapi.cfg file. If a prompt string is specified on the command line and in the ndmapi.cfg file, -P takes precedence.

When the default prompt (“Direct”) is overridden, the new prompt string is shown at the command line prompt and in the welcome banner display.

-s Suppresses standard output. Use this option to view only the completion status of a command.

-t n Enables the CLI/API trace option. The level number, n, identifies the level of detail in the trace output.

text string

Up to 32 characters.

none $ direct -s

1|2|4

Specify one of the following level numbers:

Sample Command Entry

$ direct

-PNewPrompt

$ direct -P”Test CD on Medea”

$ direct -t 4

1—Provides function entry and function exit. This is the default.

2—Provides function entry and exits and basic diagnostic information, such as displaying values of internal data structures at key points in the execution flow.

4—Enables a full trace. All diagnostic information is displayed.

2 Sterling Connect:Direct for UNIX: User Guide

Option Description Value

-e nn Defines the error level above which the CLI automatically exits. If the returned error code is greater than the error level specified, the CLI automatically exits.

Use this command within shell scripts.

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

When the CLI terminates, it returns a UNIX exit code that can be tested by the shell.

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

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

-x Displays command input on standard out. Use this command when debugging scripts.

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

-h Displays command usage information if a Sterling Connect:Direct command is typed incorrectly.

-z Appends a newline character after a prompt.

0|4|8|16

Valid values in the error level code are:

0—Indicates successful completion.

4—Indicates warning.

8—Indicates error.

16—Indicates catastrophic error.

Sterling Connect:Direct host name

1024–65535. The format is nnnnn.

none $ direct -x

none $direct -r | grep

none $ direct -h

none $ direct -z

Sample Command Entry

$ direct -e 16

$ direct -n hostname

$ direct -p 2222

“_CDPNUM_”

CLI Job Control

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

Chapter 1. Controlling and Monitoring Processes 3

enables you to edit the text of saved Processes, issue UNIX commands, and resolve Process errors without exiting and reentering the CLI. Use the following commands to switch the CLI Process:

v Press the suspend character (Control-Z) to stop or suspend the CLI Process.

v Issue the fg command to move the CLI Process to the foreground.

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

CLI History Commands

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

Command Description

!! Repeat the last command one time.

!#n Set the number of commands to store in the

!n Repeat command number <n> in the history

!<string> Repeat command beginning with the string

!? List the contents of the history buffer.

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

buffer.

<string>.

Overview of Sterling Connect:Direct Commands

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

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

Command Abbreviation Description

submit sub Makes Processes available for execution.

change process cha pro Changes the status and modifies specific characteristics,

of a nonexecuting Process in the TCQ.

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

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

stop stop Stops Sterling Connect:Direct for UNIX and returns

control to the operating system.

select process sel pro Monitors both executing Processes and Processes

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

select statistics sel stat Retrieves information from the statistics file. You can

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

view process view pro View a Process in the TCQ where the local node is the

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

4 Sterling Connect:Direct for UNIX: User Guide

Abbreviations for Common Sterling Connect:Direct Commands

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

Parameter Abbreviation

detail det

quit q

recids rec

release rel

pname pnam, pna

pnumber pnum

sunday sun

monday mon

tuesday tue

wednesday wed

thursday thu

friday fri

saturday sat

today tod

tomorrow tom

Restricting the Scripts and UNIX Commands Users Can Execute

System administrators and other network operations staff can restrict the scripts and UNIX commands that you can execute with the run task and run job Process statements. System administrators and other network operations staff can enforce the following limits on the capabilities you have with Sterling Connect:Direct:

v The capability to send or receive files; you may be limited either to sending files

only or to receiving files only.

v The locations to or from which you can send or receive files; you may be limited

to specific local or remote nodes.

Check with the system administrator for a list of specific restrictions for your user ID.

Sterling Connect:Direct Command Syntax

Use the same command syntax for commands typed at the CLI prompt or used as the command text parameter for an ndmapi_sendcmd() function. Refer to “User Exit Programs” on page 75, for details on function calls. The following conventions are used when typing commands:

v When selecting a password or user ID, do not use Sterling Connect:Direct

keywords.

v Be aware that user names and file names are case sensitive.

v Type an individual command keyword in uppercase, lowercase, or mixed-case

characters.

v Terminate all commands with a semicolon (;).

Chapter 1. Controlling and Monitoring Processes 5

v When typing commands, type the entire command name or type the first three

characters or abbreviate specific parameters. Refer to “Abbreviations for Common Sterling Connect:Direct Commands” on page 5for a list of abbreviations.

v Do not abbreviate Process statements and parameters.

v File names, group names, user IDs, and passwords are variable length strings

and can be any length.

v A Sterling Connect:Direct node name is 1–16 characters long. The name of a

record in the netmap describing a remote node is typically the remote Sterling Connect:Direct node name, but can be any string 1–256 characters long. You can also specify a remote node name as an IP address or hostname and a port number or port name.

“Generic” Parameter Value

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

PNAME = A?PROD5*

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

“List” Parameter Value

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

(pnumber1, pnumber2, pnumber3)

Submitting a Process

The submit command makes Processes available for execution and enables the software to interpret the Process statements contained in the specified files.

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

Parameter Description Values

file The name of the Process file. The file name can

include a path name indicating the location of the Process.

This parameter must be the first parameter.

file name including the path name

6 Sterling Connect:Direct for UNIX: User Guide

Parameter Description Values

class The node-to-node session on which a Process

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

A numeric value from 1 to the value of maximum

concurrent local node connections

(sess.pnode.max). The default value is 1. The

value cannot be greater than the maximum

number of local sessions with primary control.

crc Determines if crc checking is performed. This

on|off parameter overrides settings in the initialization parameter, the network map, and the Process. Note: The user must be assigned authority to

on—Turns on crc checking.

off—Turns off crc checking. The default is off.

change the crc settings in the user authority file.

hold Determines if the Process is placed in the Hold

yes | no | call queue.

yes—Specifies the Process is placed in the Hold When a Process is submitted with retain=yes or retain=call, Sterling Connect:Direct ignores the hold parameter.

queue in HI status until it is released by a change

process command. A Process submitted with

hold=yes is placed on the Hold queue even if you

specify a start time.

no—Specifies that the Process executes as soon as

resources are available. This is the default.

maxdelay How long the submit command waits for the

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

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

newname A new Process name that overrides the name

in the submitted Process.

call—Specifies that the Process is held until a

connection is established between the remote

node and the local node. At that time, the Process

is released for execution.

unlimited | hh:mm:ss |0

unlimited—Waits until the Process completes

execution.

hh:mm:ss—Waits for an interval no longer than

the specified hours, minutes, and seconds.

0—Waits until the Process completes execution. If

you specify maxdelay=0, you get the same results

as when you specify maxdelay=unlimited.

A name up to 256 characters long

Chapter 1. Controlling and Monitoring Processes 7

Parameter Description Values

notify The user e-mail to receive Process completion

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

pacct A string containing information about the

PNODE. Enclose the string in double quotation marks.

pnodeid Security user IDs and passwords at the

PNODE. The pnodeid subparameters can contain 1–64 alphanumeric characters.

prty The priority of the Process in the Transmission

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

retain Determines if Sterling Connect:Direct retains a

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

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

username@hostname or user@localhost

“pnode accounting data” up to 256 characters

id [, pswd]

id—Specifies a user ID on the PNODE.

pswd—Specifies a user password on the PNODE.If you specify pnodeid, you must also specify id. Identify the ID first and the pswd last.

1–15, where fifteen is the highest priority. The default is 10.

yes | no | initial

yes—Specifies that the system retains the Process in the Hold queue in HR status after execution.

no—Specifies that the system deletes the Process from the TCQ after execution. This is the default.

initial—Specifies that the system retains the Process in the Hold queue in HR status for automatic execution every time the Process Manager initializes.

If no start time is identified, you must issue a change process command to release the Process for execution. Do not code the startt parameter when you specify retain=initial.

sacct Specifies accounting data for the SNODE.

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

8 Sterling Connect:Direct for UNIX: User Guide

“snode accounting data” up to 256 characters. Enclose the string in double quotation marks.

Parameter Description Values

snode Identifies the name of the secondary node.

Setting this value overrides the snode value in the Process statement. The snode parameter is

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

nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn[;port

name | nnnnn]] required either on the submit command or Process statement.

name—Specifies the node name of the remote

node. The secondary node name corresponds to

an entry in the network map file.

host name—Specifies the name of the host

computer where the remote Sterling

Connect:Direct node is running.

nnn.nnn.nnn.nnn or

nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn

—Specifies the IP address of the remote node in

IPv4 or IPv6 format: nnn.nnn.nnn.nnn (IPv4) or

nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn

(IPv6).

[;port number |nnnnn]—Identifies the

communications port. You can only use this

parameter with the host name or IP address

parameters. The nnnnn value is a decimal number

from 1,024–65,535.

Chapter 1. Controlling and Monitoring Processes 9

Parameter Description Values

snodeid Specifies security user IDs and security

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

If Sterling Connect:Direct finds that a Process has no snodeid parameter or defines a snodeid parameter and the initialization parameter proxy.attempt is set to y, then any password specified on the snodeid parameter is ignored. A proxy user record is a remote user record in the userfile.cfg, which corresponds to the user name specified on the snodeid parameter. If no proxy user record exists, the snodeid parameter must contain a valid user name and password for a UNIX user who has a corresponding local user record in the userfile.cfg file.

When proxy.attempt=n and no snodeid is defined, Sterling Connect:Direct uses the submitting ID and node to find a Remote User Information record in the User Authorization Information file. If Sterling Connect:Direct cannot find a match, then that user cannot send or receive files.

id [,pswd [,newpswd]]

id—Specifies a user ID on the SNODE.

pswd—Specifies a user password on the SNODE. If you specify id, you do not have to specify pswd. This capability enables the id parameter to contain a dummy ID to be used for translation to a local ID on the remote system.

newpswd—Specifies a new password value. On certain platforms, the user password changes to the new value on the SNODE if the user ID and old password are correct (refer to documentation on the specific platform). If the SNODE is a UNIX node, the password does not change.

If you specify pswd, you must also specify id. If you specify newpswd, you must also specify pswd. Type the values in the order of id, pswd, and newpswd.

If the initialization parameters file parameter proxy.attempt is set to y, users are not required to specify a password for the snodeid parameter. This capability enables the id subparameter to contain a dummy user ID to be used for translation to a local user ID on the remote system. The use of a dummy user ID offers improved security because neither the sender nor the receiver are required to use an actual user ID.

Reserved keywords cannot be used in the

snodeid field.

10 Sterling Connect:Direct for UNIX: User Guide

Parameter Description Values

startt Identifies the date, day, and time to start the

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

date—Specifies the day (dd), month (mm), and

year (yy), which you can code as mm/dd/yyyy

or mm-dd-yyyy. If you only specify date, the time

defaults to 00:00:00, which indicates midnight.

The current date is the default. Do not code the startt parameter when you specify retain=initial.

day—Specifies the day of the week. Values are

today, tomorrow, yesterday, monday, tuesday,

wednesday, thursday, friday, saturday, and

sunday.

hh:mm:ss [am | pm]—Specifies the time of day in

hours (hh), minutes (mm), and seconds (ss). You

can specify the hour in either 12- or 24-hour

format. If you use 12-hour format, then you must

specify am or pm. The default is the 24-hour

format. The default value is 00:00:00, which

indicates midnight. If you specify only the day

value, the time defaults to 00:00:00. This means

that if you submit a Process on Monday, with

monday as the only startt parameter, the Process

does not run until the following Monday at

midnight.

&symbolic name 1

&symbolic name 2

&symbolic name n

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

The value for the symbolic parameter must be in double quotation marks if it is a keyword or contains special characters. If you want to reserve the double quotation marks when the

variable string 1

variable string 2

variable string n

The symbolic name cannot exceed 32 characters.



symbolic name is resolved in the Process, enclose the double-quoted string in single quotes, for example:

&filename = “‘filename with spaces'”

The symbolic name itself must not be a subset of any other symbolic name. (You cannot have, for example, a symbolic name called ¶m and another symbolic name called ¶meter in the same Process.)

Chapter 1. Controlling and Monitoring Processes 11

Parameter Description Values

tracel Specifies the level of trace to perform for a

Process. Tracing by Process can be turned on in the submit command or as part of the Process definition.

If you identify the snode or pnode immediately after the trace level definition, the trace level is turned on for all Processes submitted to and from the node identified.

level=0|1|2|4

snode | pnode

file=name

level—Specifies the level of detail displayed in the trace output. The default is 4.

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

snode—Specifies to trace only the SNODE SMGR.

pnode—Specifies to trace only the PNODE SMGR.

file—Specifies the name of a file where the trace output is directed. If you do not specify a file name, the file is created in the Sterling Connect:Direct working directory with the file name CMGR.TRC. The length of the name value is unlimited.

Example - Submit a Process That Runs Every Week

The following command submits the Process named payroll:

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

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

Example - Submit a Process with a Start Time Specified

The following command submits the Process named copyfil:

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

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

Example - Submit a Process with No File Value

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

Direct> sub do_copy process snode=node1 step01 copy from (

to (

pend ;

Process Submitted, Process Number = 5

file=data.data pnode

)

file=b snode

)

12 Sterling Connect:Direct for UNIX: User Guide

Example - Submit a Process and Turn On Tracing

The following command submits the Process named copy.cdp:

submit file=copy.cdp tracel=4 pnode;

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

Changing Process Parameters

The change process command modifies specified parameters for a nonexecuting Process.

You specify the Processes to be changed by Process name, Process number, secondary node name, and submitter.

You can change the class, destination node, and priority. You can place a Process on the Hold queue or release a Process from the Hold queue by issuing a change process command with either the release or hold=no parameter.

If you submit a Process with a startt parameter, Sterling Connect:Direct places the Process on the Timer queue. If a Process fails, you can move it to the Hold queue by specifying the change process command with hold=yes. Sterling Connect:Direct then places the Process in the Hold queue in HO status. You can release the Process for execution at a later time.

You can set tracing for an existing Process by setting the tracel parameter to 1, 2, or 4. You can turn off tracing for a Process by setting trace1 to 0.

Specify at least one of the following search criteria parameters:

Parameter Description Value

pname Locate the Process to be

changed by Process name.

The Process name is limited to 8 characters on Sterling Connect:Direct for Microsoft Windows and Sterling Connect:Direct for z/OS

pnumber Locate the Process to be

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

name | generic |(list)

name—Specifies the Process name, up to 8 alphanumeric characters.

generic—Specifies a nonspecific value for the Process name. This generic value,

containing pattern-matching characters,

evaluates to a list of zero or more pname strings.

list—Specifies a list of Process names. Enclose the list in parentheses, and separate each value with a comma.

number from 1–99,999 |(list)

number—Specifies the Process number.

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

Chapter 1. Controlling and Monitoring Processes 13

Parameter Description Value

snode Locate the Process to be

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

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

submitter Locate the Processes to be

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

remote node specification | generic |(list)

remote node specification—Identifies a specific remote node name.

generic—Specifies a nonspecific value for the remote node name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more remote node names.

list—Specifies a list of remote node specifications. Enclose the list in parentheses, and separate each value with a comma.

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

node specification, userid—Specifies the node specification (the Sterling Connect:Direct node name) and user ID.

generic—Specifies a nonspecific value for node specification and user ID. This generic value, containing pattern-matching characters, evaluates to a list of zero or more node specifications and user IDs.

list—Specifies a list of node specification and user ID pairs. Enclose the list in parentheses, and separate each value with a comma.

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

Parameter Description Value

class Changes the node-to-node

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

The default is 1.

14 Sterling Connect:Direct for UNIX: User Guide

Parameter Description Value

hold Moves the Process to the Hold

or Wait queue.

newsnode Specifies a new remote node

name to assign to the Process.

prty Changes the priority of the

Process on the TCQ. Sterling Connect:Direct uses the prty parameter for Process selection. A Process with a higher priority is selected for execution before a Process with a lower priority. The prty value does not affect the priority during transmission.

release Releases the Process from a

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

tracel Changes the level of trace to

perform for a Process.

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

yes | no | call

yes—Places the Process in the Hold queue in HO status until it is released by another change process command.

no—Places the Process in the Wait queue in WC (Waiting for Connection) status; the Process executes as soon as resources are available. This is the default.

call—Places the Process in the Hold queue in HC (Hold for Call) status until the remote node (SNODE) connects to the local node (PNODE) or another Process is submitted. At that time, Sterling Connect:Direct releases the Process for execution

new remote node specification

1–15, where 15 is the highest priority. If you do not specify prty, the default is

10.

none

level=0|1|2|4

level—Specifies the level of detail displayed in the trace output. The default is 4.

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

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

change process pname=cdproc newsnode=paris;

Deleting a Process from the TCQ

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

Chapter 1. Controlling and Monitoring Processes 15

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

Parameter Description Value

pname Identify the Process to delete

by Process name.

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

pnumber Identify the Process to delete

by Process number. Sterling Connect:Direct assigns the Process number when the Process is submitted. Valid Process numbers range from 1–99,999.

snode Identify the Process to delete

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

submitter Identify Processes to delete

by the node specification and user ID of the Process owner. The character length of this parameter is unlimited.

name | generic |(list)

name—Specifies the Process name up to 8 alphanumeric characters long.

generic—Specifies a nonspecific value for the Process name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more pname strings.

list—Specifies a list of Process names. Enclose the list in parentheses, and separate each value with a comma.

number |(list)

number—Specifies the Process number.

list—Specifies a list of Process numbers. Enclose the list in parentheses, and separate each value with a comma (,).

remote node specification | generic |(list)

remote node specification—Identifies a specific remote node name.

generic—Specifies a nonspecific value for the remote node name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more remote node names.

list—Specifies a list of remote node specifications. Enclose the list in parentheses, and separate each value with a comma.

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

node specification, userid—Specifies the node specification and user ID.

16 Sterling Connect:Direct for UNIX: User Guide

list—Specifies a list of node specification and user ID pairs. Enclose the list in parentheses, and separate each value with a comma.

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

delete process submitter=(dallas, cduser);

Removing a Process from the Execution Queue

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

Parameter Description Value

pname Locate the Process to

remove by Process name.

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

pnumber Locate the Process to

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

snode Locate the Process to

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

name | generic |(list)

name—Specifies the Process name, up to 8 alphanumeric characters.

generic—Specifies a nonspecific value for the Process name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more pname strings.

list—Specifies a list of Process names. Enclose the list in parentheses, and separate each value with a comma.

number from 1–99,999 |(list)

number—Specifies the Process number.

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

remote node specification | generic |(list)

remote node specification—Identifies a specific remote node name.

generic—Specifies a nonspecific value for the remote node name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more remote node names.

list—Specifies a list of remote node specifications. Enclose the list in parentheses, and separate each value with a comma.

Chapter 1. Controlling and Monitoring Processes 17

Parameter Description Value

submitter Locate the Processes to

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

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

node specification, userid—Specifies the node specification (the Sterling Connect:Direct node name) and user ID.

list—Specifies a list of node specification and user ID pairs. Enclose the list in parentheses, and separate each value with a comma.

The flush process command has the following optional parameters:

Parameter Description Value

force Forcibly terminates an executing

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

hold Places the terminated Process in

the Hold queue where it can be released for re-execution.

yes|no

yes—Specifies to forcibly and immediately terminate the Process. The SMGR also terminates immediately.

no—Specifies to terminate the Process in an orderly fashion as the step completes. The SMGR closes the statistics file and then terminates. This is the default.

yes|no

yes—Specifies to place the Process in the Hold queue in HS status after the Process is terminated.

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

flush process pname=rome force=yes;

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

flush process submitter=(alma, jones);

Stopping Sterling Connect:Direct

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

18 Sterling Connect:Direct for UNIX: User Guide

no—Specifies to delete the Process from the TCQ after the Process is terminated. This is the default.

You can specify the force, immediate, quiesce, or step parameters with the stop command.

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

Following are the parameters for the stop command:

Parameter Description

force Forcibly terminates Sterling Connect:Direct

and returns control to the operating system.

immediate Begins an immediate, but orderly shutdown

of all activity and terminates Sterling Connect:Direct. The software terminates connections, writes statistics records, closes files, and shuts down.

quiesce Runs all executing Processes to completion

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

step Shuts down Sterling Connect:Direct after all

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

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

stop force;

Viewing a Process in the TCQ

The view process command is used to view Processes in the TCQ when the local node is the PNODE. You can search by Process name, Process number, queue, secondary node, status, owner of the Process, or any combination of the search criteria parameters.

You also can specify more than one Process in the search criteria.

There are no required parameters for this command. If you do not specify an optional parameter, Sterling Connect:Direct selects all Processes executing or waiting for execution. Following are the optional parameters for the view process command:

Chapter 1. Controlling and Monitoring Processes 19

Parameter Description Value

pname Locate the Process to view

by Process name.

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

pnumber Locate the Process to view

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

queue Specifies the Processes to be

viewed by the specified queue names.

name | generic |(list)

name—Specifies the Process name, up to 8 alphanumeric characters.

generic—Specifies a nonspecific value for the Process name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more pname strings.

list—Specifies a list of Process names. Enclose the list in parentheses, and separate each value with a comma.

number from 1–99,999 |(list)

number—Specifies the Process number.

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

all | exec | hold | wait | timer

all—Selects Processes from all queues. This is the default.

exec—Selects Processes from the Execution queue.

snode View the Process by the

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

hold—Selects Processes from the Hold queue.

timer—Selects Processes from the Timer queue.

wait—Selects Processes from the Wait queue.

remote node specification | generic |(list)

remote node specification—Identifies a specific remote node name.

generic—Specifies a nonspecific value for the remote node name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more remote node names.

list—Specifies a list of remote node specifications. Enclose the list in parentheses, and separate each value with a comma.

20 Sterling Connect:Direct for UNIX: User Guide

Parameter Description Value

status Specifies the Processes to be

viewed by Process status. If

EX|HC|HE|HI|HO|HR|HS|PE

| WC | WR | WS | (list) you do not specify a status value, information is generated for all status values.

EX (Execution)—Specifies to select Processes

from the Execution queue.

HC (Held for Call)—Specifies to select

Processes submitted with hold=call.

HE (Held due to Error)—Specifies to select

Processes held due to a connection error.

HI (Held Initially)—Specifies to select

Processes submitted with hold=yes.

HO (Held by Operator)—Specifies to select

Processes held by a change process

command issued with hold=yes.

HR (Held Retain)—Specifies to select

Processes submitted with retain=yes or

retain=initial.

HS (Held Due to Execution

Suspension)—Specifies to select Processes

suspended by a flush process command

issued with hold=yes.

PE (Pending Execution)—Specifies to select

Processes submitted with a maxdelay

parameter and assigned PE status by the

Process Manager just before a Session

Manager is created to execute the Process.

After the Session Manager initializes, the

Process is placed on the Execution queue and

the status is changed to EX.

WC (Waiting for Connection)—Specifies to

select Processes that are ready for execution,

but that all available connections to the

remote node are in use.

WR (Waiting for Restart)—Specifies to select

Processes that are waiting for restart after

session failure.

WS (Waiting for Start Time)—Specifies to

select Processes waiting for a start time.

These Processes are on the Timer Queue.

list—Specifies a list of status values. Enclose

the list in parentheses, and separate each

value with a comma.

Chapter 1. Controlling and Monitoring Processes 21

Parameter Description Value

submitter Locate the Processes to view

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

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

node specification, userid—Specifies the node specification (the Sterling Connect:Direct node name) and user ID.

list—Specifies a list of node specification and user ID pairs. Enclose the list in parentheses, and separate each value with a comma.

The following command displays the specified Process number:

view process pnumber=1;

Monitoring Process Status in the TCQ

The select process command displays information about Processes in the TCQ.

The search criteria provide flexibility in selecting Processes. You can search for a Process by Process name, Process number, queue, secondary node, status, owner of the Process, or any combination of the search criteria parameters.

You also can specify more than one Process in the search criteria. You can request either a detailed report about the selected Process or a short report.

Parameter Description Value

pname Locate the Process to select

by Process name.

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

pnumber Locate the Process to select

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

name | generic |(list)

name—Specifies the Process name, up to 8 alphanumeric characters.

generic—Specifies a nonspecific value for the Process name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more pname strings.

list—Specifies a list of Process names. Enclose the list in parentheses, and separate each value with a comma.

number from 1–99,999 |(list)

number—Specifies the Process number.

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

22 Sterling Connect:Direct for UNIX: User Guide

Parameter Description Value

queue Specifies the Processes to be

all | exec | hold | wait | timer

selected by the specified queue names. The default is all.

all—Selects Processes from all queues. this is

the default.

exec—Selects Processes from the Execution

queue.

hold—Selects Processes from the Hold queue.

timer—Selects Processes from the Timer

queue.

wait—Selects Processes from the Wait queue.

snode Locate the Process by the

remote node specification | generic |(list)

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

The secondary node name typically contains the 1–16 character remote Sterling

remote node specification—Identifies a

specific remote node name.

generic—Specifies a nonspecific value for the

remote node name. This generic value,

containing pattern-matching characters,

evaluates to a list of zero or more remote

node names.

list—Specifies a list of remote node

specifications. Enclose the list in parentheses,

and separate each value with a comma.

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

Chapter 1. Controlling and Monitoring Processes 23

Parameter Description Value

status Specifies the Processes to be

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

EX|HC|HE|HI|HO|HR|HS|PE |WC|WR|WS|(list)

EX (Execution)—Specifies to select Processes from the Execution queue.

HC (Held for Call)—Specifies to select Processes submitted with hold=call.

HE (Held due to Error)—Specifies to select Processes held due to a connection error.

HI (Held Initially)—Specifies to select Processes submitted with hold=yes.

HO (Held by Operator)—Specifies to select Processes held by a change process command issued with hold=yes.

HR (Held Retain)—Specifies to select Processes submitted with retain=yes or retain=initial.

HS (Held Due to Execution Suspension)—Specifies to select Processes suspended by a flush process command issued with hold=yes.

PE (Pending Execution)—Specifies to select Processes submitted with a maxdelay parameter and assigned PE status by the Process Manager just before a Session Manager is created to execute the Process. After the Session Manager initializes, the Process is placed on the Execution queue and the status is changed to EX.

WC (Waiting for Connection)—Specifies to select Processes that are ready for execution, but that all available connections to the remote node are in use.

WR (Waiting for Restart)—Specifies to select Processes that are waiting for restart after session failure.

WS (Waiting for Start Time)—Specifies to select Processes waiting for a start time. These Processes are on the Timer Queue.

list—Specifies a list of status values. Enclose the list in parentheses, and separate each value with a comma.

24 Sterling Connect:Direct for UNIX: User Guide

+ 68 hidden pages

IBM 4J User Manual

Contents

Chapter 1. Controlling and Monitoring Processes

Overview of the Command Line Interface

Starting the CLI

Stopping the CLI

CLI Commands

CLI Job Control

CLI History Commands

Overview of Sterling Connect:Direct Commands

Abbreviations for Common Sterling Connect:Direct Commands

Restricting the Scripts and UNIX Commands Users Can Execute

Sterling Connect:Direct Command Syntax

Submitting a Process

Example - Submit a Process That Runs Every Week

Example - Submit a Process with a Start Time Specified

Example - Submit a Process with No File Value

Example - Submit a Process and Turn On Tracing

Changing Process Parameters

Deleting a Process from the TCQ

Removing a Process from the Execution Queue

Stopping Sterling Connect:Direct

Viewing a Process in the TCQ

Monitoring Process Status in the TCQ