Connect Direct
Connect Direct
Connect Direct
Users Guide
Version 4.0
CDUNXUG810
Contents
7
7 7 8 8 8 9 9 9 9 10 11 12 12 12 13 13 14 15 15 16 17 18 18 19 21 21 22
23
23 23 26 26 27
Contents
Guidelines for Using Connect:Direct Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . Command Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameter Abbreviations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Limitations on Using Programs and Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting a Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters for submit Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample submit Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting a Process That Runs Every Week . . . . . . . . . . . . . . . . . . . . . . . Submitting a Process with a Start Time Specified . . . . . . . . . . . . . . . . . . . . Submitting a Process with No File Value . . . . . . . . . . . . . . . . . . . . . . . . . . . Submitting a Process and Turning On Tracing. . . . . . . . . . . . . . . . . . . . . . . Changing Process Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deleting a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Removing a Process from the Execution Queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . Stopping Connect:Direct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Viewing a Process in the TCQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitoring the Process Status on the TCQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Determining the Outcome of a Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample Detailed Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample Summary Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Running System Diagnostics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27 27 28 28 29 29 29 30 30 36 36 37 37 37 37 40 42 44 45 48 52 58 58 59
63
63 64 65 65 66 67 67
69
69 70 71 72 72 73 73 73 74 74 75
Contents
Precompressing/Decompressing Files Using the Standalone Batch Compression Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Special Considerations for Using the Standalone Batch Compression Utility. . . Using the Standalone Batch Compression Utility . . . . . . . . . . . . . . . . . . . . . . . . ExamplePrecompressing a Text File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ExamplePrecompressing a Text File With Codepage Conversion . . . . . . . . . ExamplePrecompressing a Binary File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ExampleDecompressing a Text File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examplescsdacomp Command Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ExampleDecompressing the File on the Remote Node During the Copy Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ExampleSending Precompressed File to z/OS and Storing It as Precompressed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validating Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generating a Configuration Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reporting on the Base Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Reporting on Connect:Direct Secure+ Option for UNIX . . . . . . . . . . . . . . . . . . . Reporting on Connect:Direct UNIX for SWIFTNet . . . . . . . . . . . . . . . . . . . . . . .
76 76 77 80 80 81 81 81 82 82 83 84 84 86 87
89
Compiling Custom Programs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Writing Custom C Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Creating a Connection to Connect:Direct Using ndmapi_connect() or ndmapi_connect_c() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Terminating a Connection Using ndmapi_disconnect() or ndmapi_disconnect_c() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Receiving Responses Using ndmapi_recvresp() or ndmapi_recvresp_c() . . . . . 94 Sending a Command to Connect:Direct Using ndmapi_sendcmd() or ndmapi_sendcmd_c() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Writing Custom C++ Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
105
105 106 106 107 108 109 110 110 110 110 111 111 111 112 112 112
Contents
VALIDATE_MSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VALIDATE_REPLY_MSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . User Exit Stop Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Copy Control Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exit Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Glossary
115
Index
121
Chapter 1
Connect:Direct links technologies and moves all types of information between networked systems and computers. It manages high-performance transfers by providing such features as automation, reliability, efficient use of resources, application integration, and ease of use. Connect:Direct offers choices in communications protocols, hardware platforms, and operating systems. It provides the flexibility to move information among mainframe systems, midrange systems, desktop systems, and LAN-based workstations. Connect:Direct is based on client-server architecture. The Connect:Direct server components interact with the user interfaces (API, CLI, Connect:Direct Browser User Interface, and Sterling Control Center) to enable you to submit, execute, and monitor Connect:Direct statements and commands.
Server Components
Connect:Direct has the following server components:
Process Manager
The Process Manager (PMGR) is the daemon that initializes the Connect:Direct server environment. The PMGR provides the following functions: Initializes Connect:Direct Accepts connection requests from Connect:Direct client APIs and remote nodes Creates Command Manager and Session Manager child Processes to communicate with APIs and remote nodes Accepts requests from Command Managers and Session Managers when centralized Connect:Direct functions are required Stops Connect:Direct
Note: Any application, including End User Applications (EUA), can run on any computer as long as it can connect to the PMGR.
Command Manager
A Command Manager (CMGR) is created for every API connection that is successfully established. The number of Command Managers that a PMGR can create is system-dependent and limited by the number of file descriptors available for each UNIX Process. The number of file descriptors set up by the UNIX operating system may affect Connect:Direct operation. You must define enough file descriptors to handle the number of concurrent Connect:Direct sessions allowed, which can be as many as 999. The CMGR provides the following functions: Executes commands sent by the API and sends the results back to the API Carries out the Connect:Direct authentication procedure, in conjunction with the API, to determine access to Connect:Direct Interacts with the PMGR when executing commands
Session Manager
The Session Manager (SMGR) is created and invoked by the PMGR when resources are available and either a Process is ready to run or a remote node requests a connection with a local node. The SMGR provides the following functions: Performs the necessary Connect:Direct work Acts as a primary node (PNODE) and initiates Process execution Acts as a secondary node (SNODE) to participate in a Process initiated by the PNODE When an SMGR is created to execute a Process submitted to a node, it creates the connection to the remote node. If the SMGR is started by the PMGR to execute local Processes, the SMGR runs each Process on this session until all Processes are completed. If an SMGR is created because a remote node initiated a connection, the SMGR completes the connection. If the SMGR is started by the PMGR to execute remote Processes, the SMGR executes remote Process steps supplied by the remote SMGR until the remote SMGR completes all of its Processes. The SMGR depends on the PMGR for Transmission Control Queue (TCQ) services and other centralized services. Refer to the Transmission Control Queue on page 13 for an overview of the TCQ.
File Agent
Connect:Direct File Agent is a feature of Connect:Direct, which provides unattended file management. File Agent monitors watched directories to detect new files. When File Agent detects a new file, it either submits a default Process or evaluates the file using rules to override the default Process and to determine which Process to submit. You create rules to submit different Processes based on the following properties: Specific or partial file names File size System events
User Interfaces
You create the Processes used by File Agent on Connect:Direct; you cannot create them using File Agent. To achieve optimum performance, configure File Agent to communicate with the Connect:Direct node where it is installed. File Agent can be installed on UNIX, Windows, and z/OS operating systems. For information to help you plan how to implement File Agent, see the Managing Files with Connect:Direct File Agent chapter in your Connect:Direct administration guide or getting started guide. The Connect:Direct File Agent Help contains instructions for configuring File Agent.
User Interfaces
Connect:Direct has the following user interfaces, which enable you to create, submit, and monitor Processes.
Receive notification of data delivery events that occur or do not occur as scheduled Define rules that, based on processing criteria, can generate an alert, send an e-mail notification, generate a Simple Network Management Protocol (SNMP) trap to an Enterprise Management System (EMS), run a system command, or issue a server command Monitor for alerts, such as a server failure or a Process not starting on time Create service level criteria (SLCs) that define processing schedules, monitor Processes, files within Processes, and file transfers for compliance with these schedules, and generate alerts when the schedules are not met Analyze key operational metrics Create customized reports to document and analyze processing activity based on criteria you define
10
User Interfaces
Validate user authenticity for console-to-engine connections using one or more of four authentication methods, including password validation, host name identification, Windows domain, and TCP/IP address (or three methods in the case of the Web console, which does not support domain authentication) Identify additional Connect:Direct servers that may need to be monitored based on communications with a currently monitored server Sterling Control Center enhances operational productivity and improves the quality of service by: Ensuring that critical processing windows are met Reducing impact on downstream processing by verifying that expected processing occurs Providing proactive notification for at-risk business processes Consolidating information for throughput analysis, capacity planning, post-processing operational or security audits, and workload analysis Reducing the risk of errors associated with manual system administration, including eliminating individual server logon to view activity, and the need to separately configure each server for error and exception notifications Sterling Control Center is available for purchase as a separate product. Contact your Sterling Commerce representative to learn more about Sterling Control Center.
To learn more about Connect:Direct Browser, see the documentation on the Connect:Direct Browser CD-ROM or available online from the Sterling Commerce Documentation Library.
11
Connect:Direct Concepts
This section introduces concepts and definitions to help you understand system operations.
Processes
The Connect:Direct Process language provides instructions for transferring files, running programs, submitting jobs on the adjacent node, and altering the sequence of Process step execution. You can include one or more steps in a Process. A Process consists of a Process definition statement (Process statement) and one or more additional statements. Parameters further qualify Process instructions. The following table lists Process statements and their functions:
Function Copies files from one node to another. Alters the sequence of Process execution based on the completion code of previous steps with the if, then, else, eif (end if), goto, and exit statements. Defines general Process characteristics. Enables you to specify UNIX commands in a Process. The Process does not wait until the job has finished running before executing the next step in the Process. Enables you to specify UNIX commands in a Process. The Process waits until the job has finished running before executing the next step in the Process. Starts another Connect:Direct Process to either the local or remote node during execution of a Process. Marks the end of a Connect:Direct for UNIX Process.
run task
submit pend
12
Connect:Direct Concepts
ckpt01 process snode=unix.node step01 copy from ( file=file1 snode ) ckpt=1M to ( file=file2 disp=new pnode ) pend;
Refer to the Connect:Direct Processes Web site at http://www.sterlingcommerce.com/documentation/processes/processhome.html for instructions on building a Process.
Commands
You use Connect:Direct commands to submit Processes to the TCQ. You can also use Connect:Direct commands to perform the following tasks: Manage Processes in the queue Monitor and trace Process execution Produce reports on Process activities Stop Connect:Direct operation
13
For example, the following command submits the Process called onestep to the TCQ with a hold status of yes:
Direct> submit file=onestep hold=yes;
Network Map
During the transfer of data, the Connect:Direct server where the Process is submitted is the primary node and the secondary node is the remote node (partner). Connect:Direct identifies the remote nodes that the local node is able to communicate with through the use Connect:Direct network map (or netmap). The network map includes the names of all the remote nodes that the Connect:Direct local node can communicate with, the paths to contact those remote nodes, and characteristics of the sessions for communication. The remote Connect:Direct nodes also have network maps for their remote nodes. The following sample displays the corresponding network map entries of UNIX-Dallas, z/OS-Miami, and UNIX-Houston:
14
Connect:Direct Concepts
User Authorization
Connect:Direct can authorize local and remote users to perform certain Connect:Direct tasks. In order to use Connect:Direct, each user must have a record defined in the user authorization file, called userfile.cfg. Each local user must have a record in the user authorization file, and remote users may be mapped to a local user ID in a proxy relationship. To provide a method of preventing an ordinary user from gaining root access through Connect:Direct for UNIX, a second access file called the Strong Access Control (SACL) file is created when you install Connect:Direct and is named sysacl.cfg. The root:deny.access parameter, which is specified in the sysacl.cfg file, allows, denies, or limits root access to Connect:Direct for UNIX. If the SACL file is deleted or corrupted, access to Connect:Direct is denied to all users. For more information about specifying user authorizations in the userfile.cfg and the sysacl.cfg files, see Maintaining Access Information Files in the Connect:Direct for UNIX Administration Guide.
Process Restart
Several facilities are provided for Process recovery after a system malfunction. The purpose of Process recovery is to resume execution as quickly as possible and to minimize redundant data transmission after a system failure. The following Connect:Direct facilities are available to enable Process recovery: Process step restartAs a Process runs, the steps are recorded in the TCQ. If a Process is interrupted for any reason, the Process is held in the TCQ. When you release the Process to continue running, the Process automatically begins at the step where it halted. Automatic session retryTwo sets of connection retry parameters are defined in the remote node information record of the network map file: short-term and long-term. If you do not specify a value for these parameters in the remote node information record, default values are used from the local.node entry of the network map file. The short-term parameters allow immediate retry attempts. Long-term parameters are used after all short-term retries are attempted. Long-term attempts assume that the connection problem cannot be fixed quickly and retry attempts occur after a longer time period, thus saving the overhead of connection retry attempts. Checkpoint restartThis feature is available with the copy statement. Checkpoint restart can be explicitly configured within a copy step through the ckpt parameter. Refer to the Connect:Direct Processes Web site at http://www.sterlingcommerce.com/documentation/processes/processhome.html. If it is not configured in the copy step, it can be configured in the Initparms through the ckpt.interval parameter. (See Maintaining the Initialization Parameters File in the Connect:Direct for UNIX Administration Guide for more information on this parameter.) Run Task restartIf a Process is interrupted when a run task on an SNODE step is executing, Connect:Direct attempts to synchronize the previous run task step on the SNODE with the current run task step. Synchronization occurs in one of the following ways: If the SNODE is executing the task when the Process is restarted, it waits for the task to complete, and then responds to the PNODE with the task completion status. Processing continues. If the SNODE task completes before the Process is restarted, it saves the task results. When the Process is restarted, the SNODE reports the results, and processing continues.
15
If synchronization fails, Connect:Direct reads the restart parameter in the run task step or the initialization parameters file to determine whether to perform the run task step again. The restart parameter on the run task step overrides the setting in the initialization parameter. For example, if the SNODE loses the run task step results due to a Connect:Direct cold restart, Connect:Direct checks the value defined in the restart parameter to determine whether to perform the run task again.
Note: Run task restart works differently when Connect:Direct runs behind a connection load balancer. For more information on the considerations you need to know when running Connect:Direct in a load balancing environment, see the Connect:Direct for UNIX Release Notes, Connect:Direct for UNIX Administration Guide, and the Connect:Direct for UNIX Getting Started Guide.
Interruption of Process activity when the SNODE is a Connect:Direct for UNIX nodeWhen the SNODE is a Connect:Direct for UNIX node and the PNODE interrupts Process activity by issuing a command to suspend Process activity, deleting an executing Process, or when a link fails or an I/O error occurs during a transfer, the Process is placed in the Wait queue in WS status. If Process activity does not continue, you must manually delete the Process from the TCQ. Refer to the Connect:Direct for UNIX Users Guide for command syntax and parameter descriptions for the delete process command.
Note: You cannot issue a change process command from the SNODE to continue Process activity; the Process can only be restarted by the PNODE, which is always in control of the session.
16
Connect:Direct Concepts
After files are restored, the statistics records can be viewed using the select statistics command.
The following table displays the file names of sample shell scripts. Modify the shell scripts as required.
File Name selstat.sh send.sh recv.sh wildcard statarch.sh statrestore.sh lcu.sh spadmin.sh spcli.sh spcust_sample1.sh spcust_sample2.sh spcust_sample3.sh
Type of Shell Script select statistics send receive send multiple files to a PDS archive statistics files restore statistics files that have been archived launch the Local Connection Utility tool launch the Secure+ Option Admin Tool launch the Secure+ Option CLI (SPCLI) configure Secure+ Option for the STS protocol configure Secure+ Option for the STS protocol configure Secure+ Option to use the SSL or TLS protocol
17
Description This program submits a Process to copy a file to a remote system. MAXDELAY is used in this example, which means that the program will not finish execution until the file has been transferred. A standard c compiler is used to compile this module. Same as apicheck.c, except that it is compiled with one of the C++ compilers listed in the Connect:Direct for UNIX Users Guide. This program is a skeleton of a user exit program that works in conjunction with Connect:Direct for UNIX. It demonstrates usage of all three user exits. Same as exit_skeleton_c, except that it is compiled with one of the C++ compilers listed in the Connect:Direct for UNIX Users Guide. This is the same program as the skeleton user exit program, except that the security exit is demonstrated with code that approximates PassTicket functionality. This program exercises various commands using the SDK interface to Connect:Direct for UNIX.
apicheck.C exit_skeleton.c
exit_skeleton.C exit_sample.c
sdksample.C
Connect:Direct Files
This section describes the configuration files, illustrates the directory structure of Connect:Direct, and lists the individual files that are installed.
Description Provides information to the server to use at start up. During the installation, you identify the settings necessary for the initialization parameters file. Contains the local user information and remote user information record types. You customize this file during installation to map remote user IDs to local user IDs and create remote user information records in the user authorization information file.
18
Connect:Direct Files
Description Improves the security of Connect:Direct for UNIX and allows, denies, or limits root access control. This file is created when you install Connect:Direct. If the file is deleted or corrupted, access to Connect:Direct is denied to all users. Describes the local node and other Connect:Direct nodes in the network. You can define a remote node record for each node that Connect:Direct for UNIX communicates with. Verifies client API connection requests. Only verified clients are granted a connection. Identifies the port and host name used by a client to connect to Connect:Direct. Identifies Connect:Direct servers that a Connect:Direct client connects to. You can have multiple entries for multiple servers.
Server authentication key file Client configuration file Client authentication key file
19
Note: The secure+ directory is available only when Secure+ Option is purchased and installed.
d_dir/
ndm/
work/
etc/
src/ lib/ bin/ README apicheck.c example files ndmapi.a libcd2g.so (not HP) libcd2g.sl (HP only) libcdsna.so (not HP) libcdsna.sl (HP only) libcdsnpsna.so libcdsp.so libcdspsrvr.so libcdspsssl.so cfg/ cliapi/ security/ secure+/ certificates/ trusted.txt export/ ndmapi.cfg import/ cd_node/ log/ locks/ cdcust ttlflst1.0 svcflst1.0 cliflst1.0 cdver cdsnacfg (AIX LU6.2 only) snaver.sh (AIX LU6.2 only) tcq_convert template (Brixton SNA only) diskfree diskfree.so hostid.sh snmpflst1.0 cfg.convert spcust_sample1.sh spcust_sample2.sh spcust_sample3.sh default_recv.xlt default_send.xlt sysacl.cfg include/ xlate/ man1/ SACL/
ndmcmgr cdpmgr ndmpmgr ndmsmgr ndmcli direct ndmproc ndmproc.awk ndmstat ndmstat.awk ndmmsg ndmxlt ndmauths ndmauthc apnotify cdcustrpt cdsacomp cdstatm cfgcheck ndmumgr cdmsgutil initcnvt statarch.sh statrestore.sh sample.cd ndmview ndmview.awk initcnvt Install.bin lcu.jar lcu.sh ohj-jewt.jar (Secure+ only) runjar.jar (Secure+ only) SecureOHelp.jar (Secure+ only) SPAdmin.jar (Secure+ only) spadmin.sh (Secure+ only) SPCli.jar (Secure+ only) CPCliMessages.properties (Secure+
only)
20
Connect:Direct Documentation
Note: See the following figure to view the work directory for a node.
A d_dir/work/cd_node directory is created for each node. The following figure displays the work directory for multiple nodes and illustrates the working files created for each node, such as TCQ files:
d_dir/
ndm/
work/
cd_node_1
cd_node_2
cd_node_3
cd_node_n
TCQ, statistics file, transient files TCQ, statistics file, transient files
TCQ, statistics file, transient files TCQ, statistics file, transient files
Connect:Direct Documentation
Note: See the previous figure for details on the ndm directory structure.
See Connect:Direct for UNIX Release Notes for a complete list of the product documentation.
21
Task Overview
The following table guides you to the information required to perform Connect:Direct tasks:
Task Understanding Connect:Direct Understanding the parameters required to invoke the Command Line Interface (CLI) to submit Processes and commands Understanding the TCQ and the commands necessary to manage Processes in the queue Understanding and using Connect:Direct utilities Understanding function calls necessary to write custom programs to use with Connect:Direct Understanding user exits and user exit function calls to use with Connect:Direct Reference Chapter 1, About Connect:Direct for UNIX Chapter 2, Controlling and Monitoring Processes
Chapter 3, Process Queuing Chapter 4, Using Connect:Direct Utilities Chapter 5, Writing Custom Programs Chapter 6, Writing User Exits
22
Chapter 2
This chapter provides instructions on using the Command Line Interface (CLI) to submit Processes and commands.
Note: You can also use the Connect:Direct Browser User Interface to perform some of the procedures in this chapter. To learn more about the Connect:Direct Browser, see the users guide on the Connect:Direct Browser CD-ROM or available online from the Sterling Commerce Documentation Library.
cfgCheck utility. For more information about cfgCheck, see Validating Configuration Files on page 83. In the C shell:
23
2. Type the following command to invoke Connect:Direct CLI. Type options as required:
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.
none
$ direct -s
24
Option
Description
Value
-t n
Enables the CLI/API trace option. The level number, n, identifies the level of detail in the trace output.
1|2|4 Specify one of the following level numbers: 1Provides function entry and function exit. This is the default. 2Provides function entry and exits and basic diagnostic information, such as displaying values of internal data structures at key points in the execution flow. 4Enables a full trace. All diagnostic information is displayed.
-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.
0 | 4 | 8 | 16 Valid values in the error level code are: 0Indicates successful completion. 4Indicates warning. 8Indicates error. 16Indicates catastrophic error.
$ direct -e 16
-n name
Identifies the host name of the computer where the Connect:Direct server (PMGR) is running. Note: Invoking direct with -p or -n overrides the settings in the ndmapi.cfg file.
$ direct -n hostname
-p nnnnn
Identifies the communications port number for the Connect:Direct node. Note: Invoking direct with -p or -n overrides the settings in the ndmapi.cfg file.
$ direct -p 2222
-x
Displays command input on standard out. Use this command when debugging scripts.
none
$ direct -x
25
Option
Description
Value
-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. Displays command usage information if a Connect:Direct command is typed incorrectly. Appends a newline character after a prompt.
none
-h
none
$ direct -h
-z
none
$ direct -z
Description Repeat the last command one time. Set the number of commands to store in the history buffer. The default history buffer size is 50 commands. Repeat command number <n> in the history buffer. Repeat command beginning with the string <string>. List the contents of the history buffer.
26
Command Overview
You control and monitor Connect:Direct Processes using the following commands:
Command submit change process delete process flush process stop select process Abbreviation sub cha pro del pro flush pro stop sel pro Description Makes Processes available for execution. Changes the status and modifies specific characteristics, of a nonexecuting Process in the TCQ. Removes a nonexecuting Process from the TCQ. Removes an executing Process from the TCQ. Stops Connect:Direct and returns control to the operating system. Monitors both executing Processes and Processes waiting for execution. You can specify the search criteria and the form in which the information is presented. Retrieves information from the statistics file. You can specify the search criteria and the form in which the information is presented. 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.
Note: The CMGR currently limits the size of a Process file to 60K bytes.
27
Parameter Abbreviations
The following table lists valid abbreviations for commonly used parameters:
Parameter detail quit recids release pname pnumber sunday monday tuesday wednesday thursday friday saturday today tomorrow
Abbreviation det q rec rel pnam, pna pnum sun mon tue wed thu fri sat tod tom
28
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 Writing Custom Programs on page 89, for details on function calls. The following conventions are used when typing commands: When selecting a password or user ID, do not use Connect:Direct keywords. Be aware that user names and file names are case sensitive. Type an individual command keyword in uppercase, lowercase, or mixed-case characters. Terminate all commands with a semicolon (;). When typing commands, type the entire command name or type the first three characters or abbreviate specific parameters. Refer to the table on page 27 for a list of abbreviations. Do not abbreviate Process statements and parameters. File names, group names, user IDs, and passwords are variable length strings and can be any length. A Connect:Direct node name is 116 characters long. The name of a record in the netmap describing a remote node is typically the remote Connect:Direct node name, but can be any string 1256 characters long. You can also specify a remote node name as an IP address or hostname and a port number or port name. Generic 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. Lists 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:
29
Submitting a Process
Use the submit command to make Processes available for execution and to enable the software to interpret the Process statements contained in the specified files.
crc
Determines if crc checking is performed. This parameter overrides settings in the initialization parameter, the network map, and the Process. Note: The user must be assigned authority to change the crc settings in the user authority file.
hold
Determines if the Process is placed in the Hold queue. When a Process is submitted with retain=yes or retain=call, Connect:Direct ignores the hold parameter.
yes | no | call yesSpecifies the Process is placed in the Hold 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. noSpecifies that the Process executes as soon as resources are available. This is the default. callSpecifies that the Process is held until a connection is established between the remote node and the local node. At that time, the Process is released for execution.
30
Submitting a Process
Parameter maxdelay
Description 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.
Values unlimited | hh:mm:ss | 0 unlimitedWaits until the Process completes execution. hh:mm:ssWaits for an interval no longer than the specified hours, minutes, and seconds. 0Waits until the Process completes execution. If you specify maxdelay=0, you get the same results as when you specify maxdelay=unlimited.
newname notify
A new Process name that overrides the name in the submitted Process. 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: 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 pnodeid
A string containing information about the PNODE. Enclose the string in double quotation marks. Security user IDs and passwords at the PNODE. The pnodeid subparameters can contain 164 alphanumeric characters.
pnode accounting data up to 256 characters id [, pswd] idSpecifies a user ID on the PNODE. pswdSpecifies a user password on the PNODE. If you specify pnodeid, you must also specify id. Identify the ID first and the pswd last.
prty
The priority of the Process in the Transmission Control Queue (TCQ). A Process with a higher priority is selected for execution before a Process with a lower priority. The prty value does not affect the priority during transmission.
31
Parameter retain
Description Determines if Connect:Direct retains a copy of the Process in the TCQ. 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. Connect:Direct for UNIX does not provide a way to run a Process hourly. To do this, you must use the UNIX cron utility. 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.
Values yes | no | initial yesSpecifies that the system retains the Process in the Hold queue in HR status after execution. noSpecifies that the system deletes the Process from the TCQ after execution. This is the default. initialSpecifies that the system retains the Process in the Hold queue in HR status for automatic execution every time the Process Manager initializes.
sacct
Specifies accounting data for the SNODE. Setting this value in the submit statement overrides any accounting data specified in Process.
snode accounting data up to 256 characters. Enclose the string in double quotation marks.
32
Submitting a Process
Parameter snode
Description Identifies the name of the secondary node. Setting this value overrides the snode value in the Process statement. The snode parameter is required either on the submit command or Process statement.
Values name | host name | nnn.nnn.nnn.nnn or nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnn n:nnnn[;port name | nnnnn]] nameSpecifies the node name of the remote node. The secondary node name corresponds to an entry in the network map file. host nameSpecifies the name of the host computer where the remote Connect:Direct node is running. nnn.nnn.nnn.nnn or nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnn n: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:nnn n:nnnn (IPv6). [;port number |nnnnn]Identifies the communications port. You can only use this parameter with the host name or IP address parameters. The nnnnn value is a decimal number from 1,02465,535. For more information on specifying IP addresses and host names, see the Specifying IP Addresses, Host Names, and Ports appendix in the Connect:Direct for UNIX Administration Guide.
33
Parameter snodeid
Description Specifies security user IDs and security passwords on the SNODE. The snodeid subparameters can contain one or more alphanumeric characters. If 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. When proxy.attempt=n and no snodeid is defined, Connect:Direct uses the submitting ID and node to find a Remote User Information record in the User Authorization Information file. If Connect:Direct cannot find a match, then that user cannot send or receive files. If the initialization parameters file parameter proxy.attempt is set to y, users are not required to specify a password for the snodeid parameter. This capability enables the id subparameter to contain a dummy user ID to be used for translation to a local user ID on the remote system. The use of a dummy user ID offers improved security because neither the sender nor the receiver are required to use an actual user ID. Reserved keywords cannot be used in the snodeid field.
Values id [,pswd [,newpswd]] idSpecifies a user ID on the SNODE. pswdSpecifies a user password on the SNODE. If you specify id, you do not have to specify pswd. This capability enables the id parameter to contain a dummy ID to be used for translation to a local ID on the remote system. newpswdSpecifies a new password value. On certain platforms, the user password changes to the new value on the SNODE if the user ID and old password are correct (refer to documentation on the specific platform). If the SNODE is a UNIX node, the password does not change. If you specify pswd, you must also specify id. If you specify newpswd, you must also specify pswd. Type the values in the order of id, pswd, and newpswd.
34
Submitting a Process
Parameter startt
Description Identifies the date, day, and time to start the Process. 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. Do not code the startt parameter when you specify retain=initial.
Values [date | day] [,hh:mm:ss [am | pm]] dateSpecifies the day (dd), month (mm), and year (yy), which you can code as mm/dd/yyyy or mm-dd-yyyy. If you only specify date, the time defaults to 00:00:00, which indicates midnight. The current date is the default. daySpecifies the day of the week. Values are today, tomorrow, yesterday, monday, tuesday, wednesday, thursday, friday, saturday, and sunday. hh:mm:ss [am | pm]Specifies the time of day in hours (hh), minutes (mm), and seconds (ss). You can specify the hour in either 12- or 24-hour format. If you use 12-hour format, then you must specify am or pm. The default is the 24-hour format. The default value is 00:00:00, which indicates midnight. If you specify only the day value, the time defaults to 00:00:00. This means that if you submit a Process on Monday, with monday as the only startt parameter, the Process does not run until the following Monday at midnight.
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 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.)
variable string 1 variable string 2 variable string n The symbolic name cannot exceed 32 characters.
35
Parameter tracel
Description 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.
Values level = 0 |1 | 2 | 4 snode | pnode file=name levelSpecifies the level of detail displayed in the trace output. The default is 4. 0Terminates the trace. 1The basic level that provides function entry and function exit. 2includes level 1 plus function arguments. 4Enables a full trace. Basic diagnostic information, such as values of internal data structures at key points in the execution flow, are displayed. snodeSpecifies to trace only the SNODE SMGR. pnodeSpecifies to trace only the PNODE SMGR. fileSpecifies the name of a file where the trace output is directed. If you do not specify a file name, the file is created in the Connect:Direct working directory with the file name CMGR.TRC. The length of the name value is unlimited.
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. See Chapter 3, Process Queuing, for additional information about the TCQ.
36
Submitting 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. Submitting a Process with No File Value The following command submits a Process without a file parameter value, but with the Process statements typed at the CLI command prompt:
Direct> sub do_copy process snode=node1 step01 copy from ( file=data.data pnode ) to ( file=b snode ) pend ; Process Submitted, Process Number = 5
Submitting a Process and Turning On Tracing The following command submits the Process named copy.cdp:
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.
37
command with hold=yes. 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 pname Description Locate the Process to be changed by Process name. The Process name is limited to 8 characters on Connect:Direct for Windows and Connect:Direct for z/OS. Value name | generic | (list) nameSpecifies the Process name, up to 8 alphanumeric characters. genericSpecifies a nonspecific value for the Process name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more pname strings. listSpecifies a list of Process names. Enclose the list in parentheses, and separate each value with a comma. pnumber Locate the Process to be changed by Process number. Connect:Direct assigns the Process number when the Process is submitted. 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 116 character remote 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. For more information on specifying IP addresses and host names, see the Specifying IP Addresses, Host Names, and Ports appendix in the Connect:Direct for UNIX Administration Guide. number from 199,999 | (list) numberSpecifies the Process number. listSpecifies a list of Process numbers. Enclose the list in parentheses, and separate each value with a comma. remote node specification | generic | (list) remote node specificationIdentifies a specific remote node name. genericSpecifies a nonspecific value for the remote node name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more remote node names. listSpecifies a list of remote node specifications. Enclose the list in parentheses, and separate each value with a comma.
snode
38
Parameter submitter
Description Locate the Processes to be changed by the node specification (the Connect:Direct node name) and user ID of the Process owner. The character length of this parameter is unlimited.
Value (node specification, userid) | generic | (list) node specification, useridSpecifies the node specification (the Connect:Direct node name) and user ID. genericSpecifies a nonspecific value for node specification and user ID. This generic value, containing pattern-matching characters, evaluates to a list of zero or more node specifications and user IDs. listSpecifies a list of node specification and user ID pairs. Enclose the list in parentheses, and separate each value with a comma.
The optional parameters for the change process command are the following:
Parameter class Description 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. Moves the Process to the Hold or Wait queue. Value The default is 1.
hold
yes | no | call yesPlaces the Process in the Hold queue in HO status until it is released by another change process command. noPlaces the Process in the Wait queue in WC (Waiting for Connection) status; the Process executes as soon as resources are available. This is the default. callPlaces the Process in the Hold queue in HC (Hold for Call) status until the remote node (SNODE) connects to the local node (PNODE) or another Process is submitted. At that time, Connect:Direct releases the Process for execution
newsnode
39
Parameter prty
Description Changes the priority of the Process on the TCQ. 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. Releases the Process from a held state. This parameter is equivalent to hold=no. 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.
Value 115, where 15 is the highest priority. If you do not specify prty, the default is 10.
release
none
tracel
level = 0 | 1 | 2 | 4 levelSpecifies the level of detail displayed in the trace output. The default is 4. 0Terminates the trace. 1Is the basic level that provides function entry and function exit. 2 Includes level 1 plus function arguments. 4Enables a full trace. Basic diagnostic information, such as values of internal data structures at key points in the execution flow, are displayed.
The following command changes the remote node name for the Process named cdproc to a new remote node, paris:
Deleting a Process
Use the delete process command to remove a nonexecuting Process from the TCQ. 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:
40
Deleting a Process
Parameter pname
Description Identify the Process to delete by Process name. The Process name is limited to 8 characters on Connect:Direct Windows for and for z/OS.
Value name | generic | (list) nameSpecifies the Process name up to 8 alphanumeric characters long. genericSpecifies a nonspecific value for the Process name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more pname strings. listSpecifies a list of Process names. Enclose the list in parentheses, and separate each value with a comma.
pnumber
Identify the Process to delete by Process number. Connect:Direct assigns the Process number when the Process is submitted. Valid Process numbers range from 199,999. Identify the Process to delete by the secondary node name. This parameter can be used to specify a specific remote node, a generic value for matching remote node names (using pattern matching), or a list of multiple remote node names. The secondary node name typically contains the 116 character remote 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. For more information on specifying IP addresses and host names, see the Specifying IP Addresses, Host Names, and Ports appendix in the Connect:Direct for UNIX Administration Guide.
number | (list) numberSpecifies the Process number. listSpecifies a list of Process numbers. Enclose the list in parentheses, and separate each value with a comma (,). remote node specification | generic | (list) remote node specificationIdentifies a specific remote node name. genericSpecifies a nonspecific value for the remote node name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more remote node names. listSpecifies a list of remote node specifications. Enclose the list in parentheses, and separate each value with a comma.
snode
41
Parameter submitter
Description Identify Processes to delete by the node specification and user ID of the Process owner. The character length of this parameter is unlimited.
Value (node specification, userid) | generic | (list) node specification, useridSpecifies the node specification and user ID. genericSpecifies a nonspecific value for node specification and user ID. This generic value, containing pattern-matching characters, evaluates to a list of zero or more node specifications and user IDs. listSpecifies a list of node specification and user ID pairs. Enclose the list in parentheses, and separate each value with a comma.
The following command deletes all nonexecuting Processes submitted by user ID cduser on node dallas:
42
Parameter snode
Description 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. The secondary node name typically contains the 116 character remote 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. For more information on specifying IP addresses and host names, see the Specifying IP Addresses, Host Names, and Ports appendix in the Connect:Direct for UNIX Administration Guide.
Value remote node specification | generic | (list) remote node specificationIdentifies a specific remote node name. genericSpecifies a nonspecific value for the remote node name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more remote node names. listSpecifies a list of remote node specifications. Enclose the list in parentheses, and separate each value with a comma.
submitter
Locate the Processes to remove by the node specification (the Connect:Direct node name) and user ID of the Process owner.
(node specification, userid) | generic | (list) node specification, useridSpecifies the node specification (the Connect:Direct node name) and user ID. genericSpecifies a nonspecific value for node specification and user ID. This generic value, containing pattern-matching characters, evaluates to a list of zero or more node specifications and user IDs. listSpecifies a list of node specification and user ID pairs. Enclose the list in parentheses, and separate each value with a comma.
43
Following are the optional parameters for the flush process command:
Parameter force Description 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. Value yes | no yesSpecifies to forcibly and immediately terminate the Process. The SMGR also terminates immediately. noSpecifies to terminate the Process in an orderly fashion as the step completes. The SMGR closes the statistics file and then terminates. This is the default. yes | no yesSpecifies to place the Process in the Hold queue in HS status after the Process is terminated. noSpecifies to delete the Process from the TCQ after the Process is terminated. This is the default.
hold
Places the terminated Process in the Hold queue where it can be released for re-execution.
The following command flushes all executing Processes named Rome from the Execution queue:
The following command flushes all executing Processes on node alma submitted by user ID jones:
Stopping Connect:Direct
Use the stop command to initiate an orderly Connect:Direct shutdown sequence or forcibly terminate the software. After running 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. You can specify the force, immediate, quiesce, or step parameters with the stop command.
Note: The force parameter is required when running Connect:Direct with the LU6.2 feature on any supported platform other than AIX.
44
quiesce
step
The following command forcibly terminates Connect:Direct and returns control to the operating system:
stop force;
45
Parameter pnumber
Description Locate the Process to view by Process number. Connect:Direct assigns the Process number when the Process is submitted.
Value number from 199,999 | (list) numberSpecifies the Process number. listSpecifies a list of Process numbers. Enclose the list in parentheses, and separate each value with a comma. all | exec | hold | wait | timer allSelects Processes from all queues. This is the default. execSelects Processes from the Execution queue. holdSelects Processes from the Hold queue. timerSelects Processes from the Timer queue. waitSelects Processes from the Wait queue.
queue
snode
View the Process by the secondary node name. This parameter can be used to specify a specific remote node, a generic value for matching remote node names (using pattern matching), or a list of multiple remote node names. The secondary node name typically contains the 116 character remote 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. For more information on specifying IP addresses and host names, see the Specifying IP Addresses, Host Names, and Ports appendix in the Connect:Direct for UNIX Administration Guide.
remote node specification | generic | (list) remote node specificationIdentifies a specific remote node name. genericSpecifies a nonspecific value for the remote node name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more remote node names. listSpecifies a list of remote node specifications. Enclose the list in parentheses, and separate each value with a comma.
46
Parameter status
Description Specifies the Processes to be viewed by Process status. If you do not specify a status value, information is generated for all status values.
Value EX | HC | HE | HI | HO | HR | HS | PE | WC | WR | WS | (list) EX (Execution)Specifies to select Processes from the Execution queue. HC (Held for Call)Specifies to select Processes submitted with hold=call. HE (Held due to Error)Specifies to select Processes held due to a connection error. HI (Held Initially)Specifies to select Processes submitted with hold=yes. HO (Held by Operator)Specifies to select Processes held by a change process command issued with hold=yes. HR (Held Retain)Specifies to select Processes submitted with retain=yes or retain=initial. HS (Held Due to Execution Suspension)Specifies to select Processes suspended by a flush process command issued with hold=yes. PE (Pending Execution)Specifies to select Processes submitted with a maxdelay parameter and assigned PE status by the Process Manager just before a Session Manager is created to execute the Process. After the Session Manager initializes, the Process is placed on the Execution queue and the status is changed to EX. WC (Waiting for Connection)Specifies to select Processes that are ready for execution, but that all available connections to the remote node are in use. WR (Waiting for Restart)Specifies to select Processes that are waiting for restart after session failure. WS (Waiting for Start Time)Specifies to select Processes waiting for a start time. These Processes are on the Timer Queue. listSpecifies a list of status values. Enclose the list in parentheses, and separate each value with a comma.
submitter
Locate the Processes to view by the node specification (the Connect:Direct node name) and user ID of the Process owner. The length of this parameter is unlimited.
(node specification, userid) | generic | (list) node specification, useridSpecifies the node specification (the Connect:Direct node name) and user ID. genericSpecifies a nonspecific value for node specification and user ID. This generic value, containing pattern-matching characters, evaluates to a list of zero or more node specifications and user IDs. listSpecifies a list of node specification and user ID pairs. Enclose the list in parentheses, and separate each value with a comma.
47
queue
Specifies the Processes to be selected by the specified queue names. The default is all.
48
Parameter snode
Description Locate the Process by the secondary node name. This parameter can be used to specify a specific remote node, a generic value for matching remote node names (using pattern matching), or a list of multiple remote node names. The secondary node name typically contains the 116 character remote 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. For more information on specifying IP addresses and host names, see the Specifying IP Addresses, Host Names, and Ports appendix in the Connect:Direct for UNIX Administration Guide.
Value remote node specification | generic | (list) remote node specificationIdentifies a specific remote node name. genericSpecifies a nonspecific value for the remote node name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more remote node names. listSpecifies a list of remote node specifications. Enclose the list in parentheses, and separate each value with a comma.
49
Parameter status
Description Specifies the Processes to be selected by Process status. If you do not specify a status value, information is generated for all status values.
Value EX | HC | HE | HI | HO | HR | HS | PE | WC | WR | WS | (list) EX (Execution)Specifies to select Processes from the Execution queue. HC (Held for Call)Specifies to select Processes submitted with hold=call. HE (Held due to Error)Specifies to select Processes held due to a connection error. HI (Held Initially)Specifies to select Processes submitted with hold=yes. HO (Held by Operator)Specifies to select Processes held by a change process command issued with hold=yes. HR (Held Retain)Specifies to select Processes submitted with retain=yes or retain=initial. HS (Held Due to Execution Suspension)Specifies to select Processes suspended by a flush process command issued with hold=yes. PE (Pending Execution)Specifies to select Processes submitted with a maxdelay parameter and assigned PE status by the Process Manager just before a Session Manager is created to execute the Process. After the Session Manager initializes, the Process is placed on the Execution queue and the status is changed to EX. WC (Waiting for Connection)Specifies to select Processes that are ready for execution, but that all available connections to the remote node are in use. WR (Waiting for Restart)Specifies to select Processes that are waiting for restart after session failure. WS (Waiting for Start Time)Specifies to select Processes waiting for a start time. These Processes are on the Timer Queue. listSpecifies a list of status values. Enclose the list in parentheses, and separate each value with a comma.
submitter
Locate the Processes to select by the node specification (the Connect:Direct node name) and user ID of the Process owner. The length of this parameter is unlimited.
(node specification, userid) | generic | (list) node specification, useridSpecifies the node specification (the Connect:Direct node name) and user ID. genericSpecifies a nonspecific value for node specification and user ID. This generic value, containing pattern-matching characters, evaluates to a list of zero or more node specifications and user IDs. listSpecifies a list of node specification and user ID pairs. Enclose the list in parentheses, and separate each value with a comma.
50
Parameter detail
Description Specifies the type of report (short or detailed) that Connect:Direct generates for the selected Processes.
Value yes | no yesGenerates a detailed report. noGenerates a short report. This is the default.
The following command displays a short report for the specified Process number:
=================================================================================== SELECT PROCESS =================================================================================== PROCESS NAME NUMBER USER SUBMITTER NODE QUEUE STATUS ----------------------------------------------------------------------------------PR01 9 root cd.unix.pj EXEC EX ===================================================================================
The following command displays a detailed report for the specified Process number:
=================================================================================== SELECT PROCESS =================================================================================== Process Name => pr01 Class => 9 Process Number => 9 Priority => 8 Submitter Node => cd.unix.pj PNODE => cd.unix.pj Submitter => sub1 SNODE => cd.unix.pj Retain Process => no Header Type => p Submit Time Submit Date => 19:52:35 => 05/22/1996 Schedule Time => Schedule Date =>
Queue => EXEC Process Status => EX Message Text => -----------------------------------------------------------------------------------
51
52
Parameter pname
Description Locate the statistics to select by Process name. The Process name is limited to 8 characters on Connect:Direct for Windows and Connect:Direct for z/OS.
Value name | generic | (list) nameSpecifies the Process name, up to 8 alphanumeric characters. genericSpecifies a nonspecific value for the Process name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more pname strings. listSpecifies a list of Process names. Enclose the list in parentheses, and separate each value with a comma.
pnumber
Locate the statistics to select by Process number. Connect:Direct assigns the Process number when the Process is submitted. Specifies whether the selection of statistics file records is based on events or related to a Process.
number from 199,999 | (list) numberSpecifies the Process number. listSpecifies a list of Process numbers. Enclose the list in parentheses, and separate each value with a comma. CAEV | CAPR | (CAEV, CAPR) CAEVSpecifies that the selection of statistics file records is related to an event, such as a Connect:Direct shutdown. CAPRSpecifies that the selection of statistics file records is related to one or more Connect:Direct Processes.
reccat
53
Parameter recids
Description Specifies the statistics file records to be selected by record ID. This parameter identifies particular types of statistics records, such as a copy termination records or Connect:Direct initialization event records.
Value record id | (list) record idSelects statistics file records for the specified record ID. listSpecifies a list of Process names. Enclose the list in parentheses, and separate each value with a comma. Following are the valid record ID values: APSMLicense Management failure generated. CHGPThe change process command issued. CRHTCopyright statement. COACListen connection enabled for either API or a remote node. CSPAConnect:Direct Secure+ Option failure generated. CSTPChild Process stopped. CTRCCopy termination record. CTRMChild Process terminated. CUKNChild Process unknown status. CXITChild Process exited. DELPThe delete Process command issued. FLSPThe flush Process command issued. FMRVError occurred in function management. information receive operation. FMSDError occurred in function management. information send operation. GPRCError occurred while getting Process. IFEDThe if statement ended. LSSTThe record ID of a step on the local node. LIEXLicense expired. LWEXLicense expires within 14 days. NINFConnect:Direct information generated at startup. NMOPNetwork map file opened. NMPRThe network map is updated through Browser, Control Center, or KQV Interface. NUICInitialization complete. NUISInitialization started. NUTCTermination completed. NUTSTermination started. PERRProcess error. PFLSProcess flushed. PREDProcess ended. PRINProcess interrupted. PSAVProcess saved. PSTRProcess started. QCEXA Process moved from another queue to the EXEC queue.
54
Description
Value QCWAA Process moved from another queue to the WAIT queue. QCTIA Process moved from another queue to the TIMER queue. QCHOA Process moved from another queue to the HOLD queue. RJEDThe run job ended. RNCFRemote node connection failed. RSSTThe record ID of a step on the remote node. RTEDThe run task ended. RTSYRun task restarted. Resyncing with run task that was executing. SBEDThe submit ended. SELPThe select Process command issued. SELSThe select statistics command issued. SENDSession ended. SERRSystem error. SFSZSize of the file submitted. SGONUser signed on using KQV Interface or Command Line Interface. SHUDShutdown occurred. SIGCSignal caught. SSTRSession start. STOPThe stop command issued. SUBPThe submit command issued. TRACThe trace command issued. TZDIThe time zone of the local node represented as the difference in seconds between the time at the local node and the Coordinated Universal Time. UNKNUnknown command issued. USECSecurity check for user ID failed. USMGConnect:Direct is shutting down. XCMMCommand manager (CMGR) messages. XCPRCopy receive. XCPSCopy send. XIPTCommunication errors. XLKLLow-level TCQ record locking errors. XMSGMessage sent to user exit. XPAEParsing error occurred when a Process or command was submitted. XPAMParsing error occurred when a Process or command was submitted. XPMCProcess manager (PMGR) connection error messages.
55
Description
Value XPMLPMGR statistics log error messages. XPMPPMGR error messages when checking permission on the Connect:Direct programs. XPMRPMGR RPC and miscellaneous error messages. XPMTPMGR termination error messages. XRPMRun task or run job error messages. XRRFRelative record file access error messages. File structure is use for TCQ. XSMGSession manager (SMGR) error messages. XSQFFile access error messages. XSTAUser exit program started. XTQGA single TCQ error message group. XTQZA single TCQ error message group.
snode
Locate the statistics file record by the secondary node name. This parameter can be used to specify a specific remote node, a generic value for matching remote node names (using pattern matching), or a list of multiple remote node names. The secondary node name typically contains the 116 character remote 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. For more information on specifying IP addresses and host names, see the Specifying IP Addresses, Host Names, and Ports appendix in the Connect:Direct for UNIX Administration Guide.
remote node specification | generic | (list) remote node specificationIdentifies a specific remote node name. genericSpecifies a nonspecific value for the remote node name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more remote node names. listSpecifies a list of remote node specifications. Enclose the list in parentheses, and separate each value with a comma.
56
Parameter srcfile
Description Selects statistics based on a source file name. Note: This parameter can be abbreviated as srcf.
Value srcf=/path/file name For example: sel stat srcf=/sci/accounting/june.payroll; This parameter can be used in combination with the destfile parameter to select statistics based on a source file name and a destination file name, for example: sel stat srcf=/sci/accounting/june.payroll dest=/sci/payroll/june.payroll
startt
Selects records produced both at and since the specified time. The date or day and time are positional. If you do not specify date or day, a comma must precede time.
[date | day] [, hh:mm:ss [am|pm]] dateSpecifies the day (dd), month (mm), and year (yy), which you can code as mm/dd/yyyy or mm-dd-yyyy. If you only specify date, the time defaults to 00:00:00. The current date is the default. daySpecifies the day of the week. Values are today, monday, tuesday, wednesday, thursday, friday, saturday, and sunday. hh:mm:ss [am | pm]Specifies the time of day in hours (hh), minutes (mm), and seconds (ss). You can specify the hour in either 12- or 24-hour format. If you use 12-hour format, then you must specify am or pm. The default is the 24-hour format. The default value is 00:00:00, which indicates midnight. If you specify only the day value, the time defaults to 00:00:00.
stopt
Specifies that Connect:Direct searches for statistics records up to and including the designated date, day, and time positional parameters. If you do not specify date or day, a comma must precede time.
[date | day] [, hh:mm:ss [am|pm]] dateSpecifies the day (dd), month (mm), and year (yy), which you can code as mm/dd/yyyy or mm-dd-yyyy. If you only specify date, the time defaults to 00:00:00. The current date is the default. daySpecifies the day of the week. Values are today, monday, tuesday, wednesday, thursday, friday, saturday, and sunday. hh:mm:ss [am | pm]Specifies the time of day in hours (hh), minutes (mm), and seconds (ss). You can specify the hour in either 12- or 24-hour format. If you use 12-hour format, then you must specify am or pm. The default is the 24-hour format. The default value is 00:00:00, which indicates midnight. If you specify only the day value, the time defaults to 00:00:00.
57
Parameter submitter
Description Locate the statistics records to select by the node specification (the Connect:Direct node name) and user ID of the Process owner. The character length of the parameter is unlimited.
Value (node specification, userid) | generic | (list) node specification, useridSpecifies the node specification (the Connect:Direct node name) and user ID. genericSpecifies a nonspecific value for node specification and user ID. This generic value, containing pattern-matching characters, evaluates to a list of zero or more node specifications and user IDs. listSpecifies a list of node specification and user ID pairs. Enclose the list in parentheses, and separate each value with a comma.
detail
Specifies the type of report (short or detailed) that Connect:Direct generates for the selected Processes.
yes | no yesGenerates a detailed report. noGenerates a short report. This is the default.
The following section illustrates sample detailed and summary reports generated by the select statistics command.
The report consists of all records from August 10, 2008. A sample statistics output for two steps only is listed in the following section. Use the table in the recids on page 54 to interpret the Record ID. The Record ID can change for each Process step displayed. The completion code indicates whether the Process executed successfully or produced an error condition. To display the long text of the message, issue the ndmmsg command described in Chapter 4, Using Connect:Direct Utilities.
58
Sample output that describes all Process steps in summary form is displayed in the following table:
=================================================================================== SELECT STATISTICS =================================================================================== P RECID LOG TIME PNAME PNUMBER STEPNAME CCOD FDBK MSGID ----------------------------------------------------------------------------------P PSTR 08/10/2008 09:10:39 PR01 9 0 XSMG200I P IFED 08/10/2008 09:10:44 PR01 9 0 XSMG405I P CTRC 08/10/2008 09:10:44 PR01 9 0 XSMG405I P IFED 08/10/2008 09:10:45 PR01 9 4 XSMG400I P RTED 08/10/2008 09:10:45 PR01 9 0 XSMG400I P IFED 08/10/2008 09:10:45 PR01 9 4 XSMG400I P CTRC 08/10/2008 09:10:45 PR01 9 0 XSMG405I P CTRC 08/10/2008 09:10:45 PR01 9 8 XSMG405I P CTRC 08/10/2008 09:10:45 PR01 9 8 XSMG405I ===================================================================================
To avoid lengthy search times when issuing the select statistics command, archive or delete statistics files regularly. Also, use the startt and stopt parameters to bracket the desired stats as closely as possible. Execution of a Process generates multiple statistics records. Connect:Direct closes the current statistics file and creates a new statistics file every midnight. It can also close the current file before midnight if the file size exceeds the value set for the file.size initialization parameter. The default file size is 1 megabyte. Statistics files are in the d_dir/work/cd_node directory. Names of the statistics file are in the format Syyyymmdd.ext, where yyyy indicates year, mm indicates month, and dd indicates day. The extension (ext) begins as 001. The extension is incremented by one each time a new statistics file is created in a single day.
59
60
Parameter pmgr
Value level=0 |1 | 2 | 4 file=name levelSpecifies the level of detail displayed in the trace output. The default is 4. 0Terminates the trace. 1Is the basic level that provides function entry and function exit. 2Includes level 1 plus function arguments. 4Enables a full trace that provides basic diagnostic information, such as values of internal data structures at key points in the execution flow. fileSpecifies the name of a file where the trace output is directed. If you do not specify a file name, the file is created in the Connect:Direct working directory with the file name PMGR.TRC. The length of the name value is unlimited.
smgr
To run the trace for Session Managers created after issuing the trace command. Currently executing Session Managers are unaffected. If you run both the comm and smgr traces, trace output for both traces is directed to the file name of the trace last specified.
level=0 |1 | 2 | 4 snode | pnode | tnode file=name levelSpecifies the level of detail displayed in the trace output. The default is 4. 0Terminates the trace. 1Is the basic level that provides function entry and function exit. 2Includes level 1 plus function arguments. 4Enables a full trace that provides basic diagnostic information, such as values of internal data structures at key points in the execution flow. snodeSpecifies to trace only the SNODE SMGR. pnodeSpecifies to trace only the PNODE SMGR. tnodeIdentifies the node on which to perform the trace. If you want to gather trace information for more than one node, identify more than one node in this parameter. fileSpecifies the name of a file where the trace output is directed. If you do not specify a file name, the file is created in the Connect:Direct working directory with the file name SMGR.TRC. The length of the name value is unlimited. The default file name is SMGR.TRC.
The following sample trace commands performs a level 2 trace on the Session Manager for the node called ath3500ry and writes the output to the file Smgp.trc:
61
A partial sample trace output is illustrated in the following section. A trace identifies the Process ID and the function, the month and day, and the time in microseconds. The first column contains the Process ID. Column two indicates the month and day in the form of MM/DD. Column three indicates the time in the form of HH:MM:SSSS. The last column indicates the function. An arrow pointing to the right indicates the function was entered. An arrow pointing to the left indicates the function was exited. Some of the functions are indented, which indicates nesting. An indented arrow indicates that the function was called by the preceding function.
=================================================================================== 498 05/18 15:13:0104 cm_sendcmd_1 entered. 498 05/18 15:13:0206 -> ndm_error_destroy <- ndm_error_destroy: ok 498 05/18 15:13:0506 -> ndm_error_create <- ndm_error_create: ok 498 05/18 15:13:0708 ndm_cmds_free entered. ndm_cmds_free exited. 498 05/18 15:13:0801 ->ndm_parser_jdi 498 05/18 15:13:0806 -> ndm_error_create <- ndm_error_create: ok 498 05/18 15:13:0916 ->Parser: SELPRO 498 05/18 15:13:0926 ->bldexp <-bldexp: Null argument value, dont add. 498 05/18 15:13:1116 ->bldexp 498 05/18 15:13:1136 -> ndm_crit_comp 498 05/18 15:13:1155 ->compile <-compile <- ndm_crit_comp: Handle <-bldexp: ok . . . ===================================================================================
62
Chapter 3
Process Queuing
This chapter contains information about the Transmission Control Queue (TCQ), which includes the following: A description of the TCQ Connect:Direct activity scheduling Progression of a Process through the TCQ, including status values for the Wait, Execution, Hold, and Timer queues
63
Queue Wait
Comments The Process remains in the Wait queue until Connect:Direct establishes a session with the remote node. After a session is established, the Process moves to the Execution queue. A copy of the Process executes once, unless you specify a startt parameter value. Specify a day or time or both for the Process to start. The Process remains in the Wait queue until Connect:Direct establishes a session with the remote node. The default is no. A copy of the Process remains in the Hold queue and executes every time the Process Manager is initiated. A copy of the Process remains in the Hold queue to be executed when released. You can execute the Process by specifying the change process command with the release parameter. The default for hold is no.
retain=yes
Hold
retain=no
Wait (if no other parameters are specified) Hold Hold Hold Wait (if no other parameters are specified) Hold
hold=call
The Process remains in the queue until the remote node starts a session with the local node or another Process starts a session with that remote node. When the scheduled day or time occur, the Process is moved to the Wait queue.
startt
Timer
Each Process in the TCQ has an associated status value. Each status value has a unique meaning that is affected by the logical queue in which the Process is placed. Status values for each queue are shown in the tables in the following sections. You can use the select process command to examine
64
that status of Processes in the TCQ. For example, the following command displays all Processes in the TCQ with execution status:
Execution
submit maxdelay=0
Wait
Timer
submit startt=(day,date,time) comm error retry file allocation error CRC checking error
Hold
65
PE status are waiting for Process start messages to be exchanged between the local node and the remote node. Processes usually have PE status assigned for a very short period of time. After a Process successfully completes, it is automatically deleted from the Execution queue. A flush process command with hold=yes moves a Process from the Execution queue and places it in the Hold queue. When a session is interrupted, the Process moves from the Execution queue to the Timer queue if retry values are specified. If connection is not made before the retry values are exhausted or if retry values are not specified, the action taken depends on the conn.retry.exhaust.action parameter. By default, the Process moves to the Hold queue. The following table shows the status values for the Execution queue:
Status PE EX Comment Pending Execution is the initial queue status when a Process is submitted with maxdelay=0. Execution status indicates that the Process is executing.
Status WC
Comment This status indicates the Process is ready to execute as soon as possible, but no session is available. Other Processes may be executing with the SNODE, and no other sessions are available. This Process runs as soon as a new session is created or an existing session becomes available. This status indicates that the Process is in retry status. The number of retries and intervals between retries is specified in the network map. This status indicates the initial queue status when a Process is submitted without a hold or retain value. This Process is ready to execute as soon as possible. This status indicates that the Process is waiting for the PNODE to continue the session.
WR WA WS
66
Status WR WS
Comment Retry indicates that the Process is in retry status. The number of retries and intervals between retries is specified in the network map. Wait for Start Time status indicates that the Process was submitted with a start time or date that has not expired. When startt is reached, the Process is placed in the Wait queue for scheduling for execution. Held Retain indicates that the Process was submitted with retain=yes or retain=initial specified and has already executed. The Process can be released later by a change process command with release specified. This status indicates the Process is ready to execute as soon as possible, but no session is available. Other Processes may be executing with the SNODE, and no other sessions are available. This Process runs as soon as a new session is created or an existing session becomes available.
HR
WC
67
Processes are placed in the Hold queue by a submit command with retain=initial, retain=yes, or hold=yes parameters specified. Processes submitted with hold=call also are placed in the Hold queue. Processes are moved from the Timer queue to the Hold queue by a change process command with hold=yes specified. Additionally, Processes are moved from the Execution queue to the Hold queue by a flush process command with hold=yes specified. Processes are moved from the Hold queue to the Execution queue by a change process command with the release parameter specified. The following table shows the status values for the Hold queue:
Status HC
Comment Held for Call indicates that the Process was submitted with hold=call specified. A session started from either node causes the Process to be moved to the Wait queue in WC status. The Process is placed in the Execution queue when the Process is selected for execution. Held Initially indicates that the Process was submitted with hold=yes specified. The Process can be released later by a change process command with release or hold=no specified. Held due to error specifies that a session error or other abnormal condition occurred. Held by Operator indicates that a change process hold=yes was specified. Held Retain indicates that the Process was submitted with retain=yes or retain=initial specified and has already executed. The Process can be released later by a change process command with release specified. Held for Suspension indicates that the operator issued a flush process command with hold=yes specified. The Process can be released later by a change process command with release specified.
HI
HE HO HR
HS
68
Chapter 4
Connect:Direct for UNIX provides tools and utilities to assist you in the following tasks: Working With Translation Tables Accessing Connect:Direct Messages Using License Key File Notification Precompressing/Decompressing Files Using the Standalone Batch Compression Utility Validating Configuration Files Generating a Configuration Report
69
# This file contains an example of defining an ASCII-to-EBCDIC translation table and # then changing it to translate lowercase to uppercase. # # Define the ASCII-to-EBCDIC table. offset=0 00 01 02 03 04 05 06 07 08 05 15 0B 0C 0D 0E 0F 10 11 12 13 3C 15 16 17 18 19 1A 1B 1C 1D 1E 1F 40 5A 7F 7B 5B 6C 50 7D 4D 5D 5C 4E 6B 60 4B 61 F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 7A 5E 4C 7E 6E 6F 7C C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 D7 D8 D9 E2 E3 E4 E5 E6 E7 E8 E9 AD E0 BD 5F 6D 79 81 82 83 84 85 86 87 88 89 91 92 93 94 95 96 97 98 99 A2 A3 A4 A5 A6 A7 A8 A9 C0 4F D0 A1 7F 80 81 82 83 84 85 86 87 88 89 8A 8B 8C 8D 8E 8F 90 91 92 93 94 95 96 97 98 99 9A 9B 9C 9D 9E 9F A0 A1 A2 A3 A4 A5 A6 A7 A8 A9 AA AB AC AD AE AF B0 B1 B2 B3 B4 B5 B6 B7 B8 B9 BA BB BC BD BE BF C0 C1 C2 C3 C4 C5 C6 C7 C8 C9 CA CB CC CD CE CF D0 D1 D2 D3 D4 D5 D6 D7 D8 D9 DA DB DC DD DE DF E0 E1 E2 E3 E4 E5 E6 E7 E8 E9 EA EB EC ED EE EF F0 F1 F2 F3 F4 F5 F6 F7 F8 F9 FA FB FC FD FE FF # # Change the lowercase characters to uppercase. offset=61 C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 D7 D8 D9 E2 E3 E4 E5 E6 E7 E8 E9
Each byte stores the character value for the target character set. The source character set is used as an index into the table. For example, an ASCII blank (Hex 20) would locate the byte at offset Hex 20 in the translation table. If the byte at location Hex 20 contains Hex code 40, that would translate to an EBCDIC code indicating a blank character.
The parameters for the ndmxlt command are listed in the following section:
Parameter -ssourcefile Description The path and file name of the translation table source file. If no value is specified, input is read from STDIN. The path and file name of the translation table output file. Values Path and name of translation table Path and name of translation output file
-ooutputfile
70
Parameter -rradix
Description The radix or base of the source file input data. All numeric values whether from command line options or input data are interpreted based on the radix setting.
Values x|d|o xHexadecimal. This is the default. dDecimal oOctal The default is x.
-ffiller
A filler byte value. The entire table is initialized to this value before the input data is scanned and applied to the table.
Any keyboard character, number, or special character, plus control characters entered using a preceding slash. For example, \0 is null.
-m
The path and file name of a model translation table. If specified, the model table is read in and then the input data is scanned and applied to the table. This capability permits creating a number of different tables that are variations from a single base table without having to specify all 256 bytes of input data for each table.
This section provides examples of how to create a translation table or modify an existing translation table.
4. Copy the modified file to cd_dir/ndm/src and name it UpperCaseEBC.sxlt. 5. Compile the new translation table using the following syntax:
71
6. To use this translation table, add the following sysopts parameter to the copy statement:
2. Copy the modified file to cd_dir/ndm/src. 3. Type the following command to compile this file and create a translation table called fourLineUpperCase.xlt:
4. To use this translation table, add the following sysopts parameter to the copy statement:
copy from file=filename to file=filename sysopts=":xlate.tbl=pathname/FourLineUpperCase.xlt:"
To specify a customized table for data translation, include the following sysopts subparameter in the copy statement, where pathname/filename identifies the translation table:
copy from file=filename to file=filename sysopts=":xlate.tbl=pathname/filename:"
72
Refer to the UNIX section of the Connect:Direct Processes Web site at http://www.sterlingcommerce.com/documentation/processes/processhome.html for additional details concerning translation table specification with a copy statement.
Diagnostics
The following table displays the error messages that are generated by ndmxlt:
Diagnostic Number XXLT001I XXLT002I XXLT003I XXLT004I XXLT005I XXLT006I XXLT007I XXLT008I Description Invalid directive Input file open error Model file open error Invalid filler value Invalid offset value Invalid radix value Invalid table value Table data out of bounds
73
XxxxnnnI Where: X Indicates Connect:Direct xxx is a 3-character Connect:Direct component identifier nnn is a 3-digit decimal number I is the standard, though not required, suffix
message id [long.text detailed message explanation] [mod.name issuing module name] short.text message summary
XCPS008I:\ :mod.name=NUSMCP00.C:\ :short.text=File is not VB datatype.:\ :long.text=File is not variable block. Change sysopts datatype to\ either binary or text to transfer this file.\ \nSYSTEM ACTION-> the copy step failed and CD processing\ continued with the next process step.\ \nRESPONSE-> change the sysopts datatype to either\ binary or text.:\
74
Following are the parameters for the ndmmsg command. If you do not specify an l or s parameter, both short and long text are displayed.
Parameter -f -l -s Description Specifies the name of the message file. Displays the long text of a message. Displays the short text of a message.
rc=&rc fdbk=&fdbk mod.name=NUCMRG00.C func.name=ndmapi_sendcmd short.text=CMGR RPC call returns NULL long.text=The ndmapi_sendcmd RPC call made by the API to the CMGR returns a NULL pointer. There is probably an RPC error. ndm.action=None user.action=First, check if the ndmcmgr is still running; it could have been killed accidently. If so, then abort the current CLI and restart the CLI. If the same problem occurs again, try to increase the value of wait time (if set) in the API configuration file (ndmapi.cfg).
75
The following examples illustrate sample output for the apnotify command:
#apnotify -t Response from Connect:Direct PMGR timed out. Suggestion: Try again with a higher timeout.
#apnotify License file update: license file last updated on Fri Aug 6 08:46:28 2003 No changes to the license file since the last update were detected. A license file reread can be forced by doing an "apnotify -f".
76
-s -a If you precompress a file with the cdsacomp utility on a Connect:Direct for UNIX node, then you cannot specify a checkpoint interval in your Connect:Direct Process if you decompress the file as it is received by the remote node. When you are copying a precompressed file to z/OS without :precomp=yes: (for deferred decompression): The Copy operation must specify DCB information for the destination file. The physical block size of the destination file on Connect:Direct for z/OS must match the logical block size of the precompressed source file on Connect:Direct for UNIX. The logical block size of the source file defaults to 27920 unless overridden by the -b parameter.
cdsacomp
-i -o
77
Parameter -z
Description Use this option with -m compress to override default compression values. This argument is optional. When decompressing, the values used during compression are used.
Values level, window, memory levelCompression level. The range is 19. The default is 1. 1Provides the least compression, but is the fastest. 9Provides the most compression, but is the slowest. windowThe size of the compression window and history buffer. Increasing the window increases the compression, but uses more virtual memory. The range is 915. The default is 13. memoryThe amount of virtual memory to allocate. The range is 19. The default is 4. 1Uses the least virtual memory. 9Uses the most virtual memory.
-x
Use this option to translate the file. If this parameter is not specified, the file is not translated. This parameter is mutually exclusive with -codepage.
full path to translate table file | relative path to translate table file
-p
Use this option to specify codepages for file conversion. Default is no codepage translation. This parameter is mutually exclusive with -xlate.
78
Parameter -d
Description Specify the datatype of the file. When you use -m compress, the datatype values result in the following: text Strips newline characters from each record Supports -s and -a parameters Uses data attributes of blocksize=23040, recfm=vb, lrecl=23036, dsorg=ps binary Uses data attributes of blocksize=23040, recfm=u, lrecl=0, dsorg=ps Does not support -s and -a parameters VB Does not support -x, -p, -s, and -a parameters Uses data attributes of blocksize=23040, recfm=vb, lrecl=23036, dsorg=ps When you use -m decompress, the datatype values result in the following: text Inserts newline characters into each record Supports the -s parameter binary Does not support the -s parameter VB Does not support -x, -p, and -s parameters
-b
Specify the block size of the output file. This parameter is valid only when you specify -m compress for the compression option.
-s
Use this option to strip trailing blanks. This parameter is valid only when you specify -d text for the datatype of the file.
79
Parameter -a
Description Use this option to replace zero-length records with a single, blank character. This parameter is valid only when you specify the following: -d text and -m compress.
Values y|n yyes nno The default is y. Specify n if the data is copied to an i5OS or mainframe node.
-h
cdsacomp -m -d -i -o -x -s
cdsacomp -m -d -i -o -p
80
cdsacomp -m -d -i -o -x
cdsacomp -h
81
ExampleDecompressing the File on the Remote Node During the Copy Step
The precomp=yes parameter is used when the file was compressed by the cdsacomp utility prior to this Process. The file is transferred by this Process as a pre-compressed file. It is then decompressed by special processing as it is received on the remote node.
sample process snode=cdunix1 step01 copy from ( file=/home/cd/upload/compressed.file sysopts=:precomp=yes: pnode ) to ( file=/home/cd/download/decompressed.file snode disp=rpl ) pend;
sample process snode=cdunix1 step01 copy from ( file=/home/cd/upload/compressed.file sysopts=:datatype=binary: pnode ) chkpt=2M to ( file=upload.compressed.file dcb=(blksize=27920, lrecl=0, dsorg=ps, recfm=u) snode disp=(new,catlg) ) pend;
82
By default, cfgCheck is run with no arguments and attempts to find all five of the configuration files in the current working directory. If all of the Connect:Direct components are not installed, then some of the files will not be found. For example, if the Command Line Interface (CLI) is installed but the Connect:Direct server is not installed, only the ndmapi.cfg file will exist in the installation directory. Therefore, only the ndmapi.cfg file will be validated. When cfgCheck is run with no arguments, the utility will report that the other configuration files were not found.
Note: Before you can execute cfgCheck, you must set the NDMAPICFG environment variable. For more information, see Starting the CLI on page 23.
$ cfgCheck -v -h -f filename.cfg
The arguments for the cfgCheck command are listed in the following table:
Arguments No arguments (default) Description When no arguments are specified and cfgCheck is run by a non-root user, it searches the cfg/ directory for the following configuration files: initparm.cfg, netmap.cfg, userfile.cfg, and ndmapi.cfg. When a root user runs cfgCheck, the utility also searches the SACL/ directory to locate the sysacl.cfg file. Prints the help screen and exits. Turns on tracing and prints verbose debug information. Specifies a configuration file name to validate, where filename is the name of one of the configuration files. You can specify multiple -f arguments. When the -f argument is used, cfgCheck will not automatically search for other configuration files from the file specified. Note: To validate the sysacl.cfg file, you must have root access or have effective permissions of root.
-h -t -f filename.cfg
83
Note: Default values are computed by the utility based on the location and name of the installed Connect:Direct for UNIX and are provided in brackets [ ]. Press Enter to accept the default values.
2. Type the full path where Connect:Direct is installed and press Enter. 3. Type the full path and name for the report that will be generated and press Enter.
84
4. The report is generated in the location you specified, and any error messages are displayed as shown in the following example:
% cdcustrpt Enter full path of Connect:Direct destination directory:[/sci/users/jbrown1/cd40]: Enter full path and name for this support report file:[/sci/users/jbrown1/cd40/etc/cd.support.rpt]: ls: /sci/users/jbrown1/cd40/ndm/SACL: Permission denied cdcustrpt ended
In this example, the user does not have root access, so the Strong Access Control File (sysacl.cfg) can not be accessed. The following example shows an excerpt from a sample report:
########################################################################### ####### Connect:Direct for UNIX 4.0.00 configuration report ####### ########################################################################### Connect:Direct for UNIX Version 4000, Build 00, IBM/RS6000 AIX, Fix date: 01OCT2007 Install directory: /sci/users/jbrown1/cd40 Local Node name: jb_aix40 Report for: jbrown1 ========================================================= ===== Begin: Environment and system information ===== ========================================================= System: AIX skyglass 3 5 00CE208E4C00
Disk usage: Filesystem 512-blocks Free %Used Iused %Iused /dev/hd4 262144 64216 76% 2479 4% /dev/hd2 8126464 2708688 67% 37802 4% /dev/hd9var 262144 18448 93% 613 2% /dev/hd3 786432 363600 54% 424 1% /dev/fwdump 524288 507752 4% 17 1% /dev/hd1 262144 216520 18% 167 1% /proc /dev/hd10opt 524288 52168 91% 3688 6% /dev/fslv00 121634816 13629040 89% 264984 15% scidalnis01:/export/nis01 1677670392 512499192 70%
Mounted on / /usr /var /tmp /var/adm/ras/platform /localhome /proc /opt /sci 0 -1% /home/nis01
Memory statistics: System Configuration: lcpu=4 mem=3824MB kthr memory page faults cpu ----- ----------- ------------------------ ------------ ----------r b avm fre re pi po fr sr cy in sy cs us sy id wa 1 1 400072 232777 0 0 0 0 0 0 4 1805 197 0 1 99 0
85
All secure+ nodes: ************************************************************** * Secure+ Command Line Interface * * Connect:Direct for UNIX v4.0.00 * *------------------------------------------------------------* * Copyright (c) 1999, 2008 Sterling Commerce Inc. * * All Rights Reserved. * ************************************************************** SPCLI> display all; name=.Local baserecord=brown_aix38 type=l protocol=tls override=n authtimeout=120 stsenablesig=n stsenableautoupdate=n stslimitexportversion=y stsenableenc=y stsencalgs=(ideacbc128,tdescbc112,descbc56) stsauthlocalkey=0305.095A.44E3.BD87.F476.45E8.09B1.FCCA.45ED.67B0.01AD stsprevauthkeyexpdatetime= stssiglocalkey=0204.BABA.613D.2FA5.AAE6.0BD4.5847.B610.A17F.C7DD.0AA2 stsprevsigkeyexpdatetime= ssltlsseaenable=n seacertvaldef= ssltlstrustedrootcertfile=/home/nis01/jbrown1/CertificateWizard/cert.crt ssltlscertfile=/home/nis01/jbrown1/CertificateWizard/athena.selfsigned.keycert.txt ssltlsenablefipsmode=n ssltlsenableclientauth=n ssltlsenablecipher=(TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA) 2007/10/19 14:27:37 parmfile upgraded: SPV4 2007/03/27 09:25:14 jbrown1 2007/03/22 09:54:55 jbrown1
86
[connection.info] # Connection information for Connect:Direct's API port. (Used when forwarding files to the back office.) Comm.Info="spyglass;10102" Userid="jbrown1" Passwd="********"# this is a test #ClientInfo="/sci/users/jbrown1/swift31/ndm/SwiftNet/Version3/program/<Encrypted userid/password file generated by the LCU>"
87
88
Chapter 5
The Connect:Direct Application Programming Interface (API) allows you to write custom programs in either C or C++ to use with Connect:Direct. With the C functions or the C++ classes, you can create programs to perform the following tasks: Establish a connection to the Connect:Direct server Disconnect from the server Receive command responses from the server Send commands to the server This chapter describes the format of the Connect:Direct API functions and classes and provides samples of their use. Sample programs are provided that use the Connect:Direct API functions and classes to issue commands and receive responses from the Connect:Direct server.
C++ Compiler IBM XL C++ V8.0 for AIX SPARC/x86 C++5.7 aCC: HP ANSI C++ B3910B A.03.73 aCC: HP ANSI C++ B3910B A.06.07 c++ version 3.3.3
89
Use the commands defined in the following table to compile a custom C++ program using the C++ API calls:
Platform AIX 32-bit 64-bit Sun 32-bit
/opt/SUNWspro/bin/CC -DBSD_COMP -I../include -o sdksample sdksample.C ../lib/ndmapi.a -L/usr/ucblib -L/usr/lib -lsocket -lrpcsoc -lnsl -lelf -ldl /usr/vacpp/bin/xlC -qinline -I../include -+ -o sdksample sdksample.C ../lib/ndmapi.a -lbsd -ldl -lsrc /usr/vacpp/bin/xlC -q64 -qinline -I../include -+ -o sdksample sdksample.C ../lib/ndmapi64.a -lbsd -ldl -lsrc
Note: If /usr/ucblib is not in the LD_LIBRARY_PATH variable, add -R/usr/ucblib to the compile command. 64-bit
/opt/SUNWspro/bin/CC -xarch=generic64 -DBSD_COMP -I../include -o sdksample sdksample.C ../lib/ndmapi64.a -L/usr/ucblib/sparcv9 -L/usr/lib/sparcv9 -L/usr/ucblib/amd64 -lsocket -l -lnsl -lelf -ldl -R/usr/ucblib/sparcv9 -R/usr/ucblib/amd64
To build a C++ program using the C API calls, such as the apicheck.C sample program, replace the sdksample.C parameter with the name of the C++ program and rename the output file parameter, -o sdksample, to the name of the output file you want to create such as apicheck.
90
C Compile Command
64-bit
HP 32-bit 64-bit
/opt/ansic/bin/cc -I../include -o apicheck apicheck.c ../lib/ndmapi.a -lrpcsoc -lnsl -ldld -Wl,+s -lcl -lstd_v2 -lCsup_v2 /opt/ansic/bin/cc +DD64 -I../include -o apicheck apicheck.c ../lib/ndmapi64.a -L/usr/lib/pa20_64 -lrpcsoc -lnsl -ldld -Wl,+s -lcl -lstd_v2 -lCsup_v2
Note: A 64-bit Linux OS installation is required to compile 64-bit binaries. LinuxS390 32-bit 64-bit
gcc -m31 -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi.a -ldl -lnss_nis /usr/lib/libstdc++.so.5 gcc -I../include -O -DLINUX -o apicheck apicheck.c ../lib/ndmapi64.a -ldl -lnss_nis /usr/lib64/libstdc++.so.5
91
Use the following Connect:Direct API functions for C and C++ programs:
C Function ndmapi_connect_c()
Description Establishes a connection with the server. Specify the node to connect to in the ndm_nodespec pointer or in the CLI/API Configuration Information file. If the call is successful, NDM_NO_ERROR is returned. Control returns to the application when the connection is established and is ready for the first API request. Sends commands to Connect:Direct. You must provide the command text. The resp_moreflag is a pointer to the flag indicating that more responses are pending for the executed command. Invoke ndmapi_recvresp_c() for C programs or ndmapi_recvresp() for C++ programs to retrieve the extra responses. Only the select process and select statistics commands require the use of ndmapi_recvresp_c() for use with C and ndmapi_recvresp() for use with C++. Receives responses to commands sent to Connect:Direct. The contents of the response buffer are returned. Terminates the API connection.
ndmapi_sendcmd()
ndmapi_sendcmd_c()
ndmapi_recvresp()
ndmapi_recvresp_c()
ndmapi_disconnect()
ndmapi_disconnect_c()
Three types of Connect:Direct command responses are returned by these functions. Informational responses return information about the submitted command. Data responses, stored in the resp_buffer, contain data records. Error responses return ERROR_H, a pointer to a linked list of all errors found. The ID field values are fixed for use when debugging. The msgid, feedback, and rc fields are specified by Connect:Direct and are referred to in message text. The subst field points to a string that contains substitution variable information to be inserted appropriately in the message text. The error control structure keeps track of the current and total number of errors. You can move through the errors by using the next pointer in error entry blocks.
92
#define NDM_ERR_ENT_T struct NDM_ERR_ENT_S #define NDM_ERR_ENT_H NDM_ERR_ENT_T * #define NDM_ERR_CTL_T struct NDM_ERR_CTL_S #define ERROR_H NDM_ERR_CTL_T * struct NDM_ERR_ENT_S { int32 id; char msgid[MSGIDLEN]; int32 feedback; int32 rc; char *subst; NDM_ERR_ENT_H next; }; struct NDM_ERR_CTL_S { int32 id; int32 cur_entry; int32 num_entries; NDM_ERR_ENT_H next; };
ndm_hostname, char *
ndm_portname
The following table describes the parameters for the ndmapi_connect() or ndmapi_connect_c() function:
Description A pointer to a Connect:Direct-defined structure that contains error information or status information. A pointer to the text specification of the Connect:Direct host to which the connection is made. If this parameter is not specified, the host name is determined by first checking the environment variable TCPHOST. If no value is specified, the tcp.host.name field in the CLI/API configuration file is checked. If no value is specified, the gethostbyname() command is invoked and the default value of ndmhost is used.
93
Parameter ndm_portname
Description A pointer to the host port number. If this parameter is not specified, the environment variable TCPPORT is checked. If no value is specified, the value of the tcp.port in the CLI/API configuration file is checked. If no value is specified, the default value 1363 is used.
Value Pointer
Following are the return codes for the ndmapi_connect() or ndmapi_connect_c() function:
Description A session was established with the server. A session was not established with the server. Consult the error structure for detailed error status.
The following sample function illustrates the use of ndmapi_connect() to connect to the sun1 host:
void ndmapi_disconnect
There are no parameters and no return codes for ndmapi_disconnect() or ndmapi_disconnect_c(). Following is a sample ndmapi_disconnect() function:
ndmapi_disconnect ();
94
Parameter error
Description A pointer to a Connect:Direct-defined structure that contains error information or status information. A pointer to the length, in bytes, of the application buffer to receive the response. The API sets this parameter to the number of bytes returned. A pointer to the application buffer that receives the command or submit response. This buffer should allocate 4096 bytes. The format of resp_buffer is a free-form text record structure. Field names are four characters long and all uppercase. The data can be any length and can include blanks. The structure is:
field name=data | field name=data |...
Value Pointer
resp_length
Pointer to number of bytes returned or 0 if you no longer want to receive responses. Setting this field to zero purges all queued responses. A local buffer, with a size greater than or equal to that set by resp_length and filled in by ndmapi_recvresp() or ndmapi_recvresp_c(). The CLI passes the resp_buffer to AWK for parsing. Valid values include: ADMNConnect:Direct administrator name ADPHConnect:Direct administrator phone number CCODCompletion code CKPTCheckpoint CLASClass DBYWBytes written DBYXBytes received DCODDestination completion code DDAYSubmit date DDS1Destination disposition 1 DDS2Destination disposition 2 DDS3Destination disposition 3 DESCConnect:Direct administrator description DFILDestination file DMSGDestination message ID DNVLDestination number of volumes DRCWRecords written DRUXRUs received DVOLDestination volume array ECMPExtended compression ON or OFF
resp_buffer
For example:
SUBM = username | PNUM = 12 | PNAM = proc1 |...
95
Description
Value FROMCopy sending node LCCDLocal completion code LCLPLocal IP address and port number LKFLLink fail LMSGLocal message ID LNODLocal node MSGIMessage IDMSGTMessage text MSSTShort text OCCDOther completion code OERROther node in error OMSGOther message ID PACCPNODE account PFILProcess file PNAMProcess name PNODPNODE PNUMProcess number PPMNPDS member name PRTYPriority QUEUQueue RECCRecord category RECIRecord ID RETARetain Process RMTPRemote IP address and port number RSTRProcess restarted RUSZRU Size SACCSNODE account SBIDSubmitter node ID SBNDSubmitter node name SBYRBytes read SBYXBytes sent SCMPStandard compression SCOD Source completion code SDDYSchedule date SDS1Source disposition 1 SDS2Source disposition 1 SDS2Source disposition 2 SDS3Source disposition 3
96
Description
Value SELAElapsed time of the event SFILSource file SMSGSource message ID SNAMStep name SSTAStart time of the event STARStart log date/time for record STATProcess status SNODSNODE SNVLSource number of volumes SOPTSYSOPTS record SRCRRecords read SRUXRUs sent STIMSchedule time STOPStop time of the event SUBMSubmitter ID SUBNSubmitter node SUMMSummary output selector SVOLSource volume array TIMESubmit time XLATTranslation
resp_moreflag
Indicates that more ndmapi_recvresp() or ndmapi_recvresp_c() calls must be issued for more information. This flag occurs only on select process and select statistics commands.
None
Description The function completed successfully. An error occurred. Consult the error structure for detailed error status. Data is truncated because the receiving buffer is too small.
97
int32 rc, resp_length; int32 resp_moreflag; char resp_buffer[makbuf]; rc= ndmapi_recvresp (error, &resp_length, resp_buffer, &resp_moreflag );
int32 rc, resp_moreflag; struct sendcmd_data ret_data; rc=ndmapi_sendcmd (error, "select process pnumber=2,", &resp_moreflag, &ret_data );
Description A pointer to a Connect:Direct-defined structure that contains error information or status information. A pointer to the null-terminated text string that specifies the command to send to Connect:Direct. The command text must be followed by a semicolon and terminated with a null. When you use the submit=filename command from the API, ensure that you allocate enough storage for the Process text. The text of the Process submitted is returned in the text string associated with this parameter when the function completes. If you do not allocate enough storage for the Process text, a core dump can result.
resp_moreflag
A pointer to the flag that indicates that more responses are pending for the command just executed. Invoke ndmapi_recvresp() or ndmapi_recvresp_c() to retrieve the extra responses.
Pointer to a flag
98
Parameter ret_data
Description A pointer to a structure containing internal response information for a command. The structure is:
struct sendcmd_data { char * cmd_name; ulong cmd_id; long data1; long data2; long data3; };
sendcmd_data
Provides the caller with some information about the user request. Because parsing of command text occurs at the CMGR, the End User Application (EUA) has no way to identify the command that was submitted, unless it generated the text. A pointer to a string with the name of the command submitted. The CLI uses this pointer to display completion messages. This field enables you to display unique completion messages without any knowledge of a specific command in the EUA. A four-byte identifier of the command that was found in the command text. Following are the four-byte identifiers:
/**************Command IDs*******************/ #define CHANGE_PROCESS 0x43484750 /* "CHGP" */ #define DELETE_PROCESS 0x44454c50 /* "DELP"*/ #define FLUSH_PROCESS 0x464c5350 /* "FLSP" */ #define SELECT_PROCESS 0x53454c50 /* "SELP"*/ #define SELECT_STATISTICS 0x53454c53 /* "SELS" */ #define SUBMIT 0x5355424d /* "SUBM" */ #define TRACE_API 0x41504920 /* "API " */ #define TRACE_CMGR 0x434d4752 /* "CMGR" */ #define TRACE_SMGR 0x534d4752 /* "SMGR" */ #define TRACE_PMGR 0x504d4752 /* "PMGR" */ #define TRACE_COM 0x434f4d4d /* "COMM"*/ #define TRACE 0x54524143 /* "TRAC" */ #define STOPNDM 0x53544F50 /* "STOP" */
cmd_name
cmd_id
Four-byte identifier
The CLI uses these identifiers to ensure that rules are being followed. For instance, if an ndmapi_sendcmd returns with the resp_moreflag set and the cmd_id is not SELECT_STATISTICS or SELECT_PROCESS, the CLI generates an error. data1, data2, and data3 For future expansion. data1 is used with the submit command to return the Process number. data2 is used with the submit command to return the result of the Process (0, 4, 8, or 16)
Description The function completed successfully. An error occurred. Consult the error structure for detailed error status.
99
To use the ConnectDirectSession class, your application must include the cdunxsdk.h header file provided in the installation and must link with the ndmapi.a file. Following is a sample ConnectDirectSession class program:
#include "cdunxsdk.h" #include <iostream.h> #include <string.h> void getError(ConnectDirectSession& cdSess); main() { ConnectDirectSession cdSess; char processText[16384]; if (cdSess.SessionINF->Connect() == CD_SUCCESS) { strcpy(processText,"submit maxdelay=unlimited sdksample process snode=SNODENAME "); strcat(processText,"copy00 copy from (file=sample.txt pnode)"); strcat(processText," to (file=sample.000 snode disp=rpl) ;"); if (cdSess.SessionINF->SendCommand(processText) == CD_SUCCESS) { printf("%s completed, pnumber = %ld.\n", cdSess.SessionINF->GetCommandName(), cdSess.SessionINF->GetProcessNumber()); sprintf(processText, "SELECT STATISTICS PNUMBER=%ld DETAIL=YES ;", cdSess.SessionINF->GetProcessNumber()); (cdSess.SessionINF->SendCommand(processText) == CD_SUCCESS) {
100
} else { getError(cdSess); } } else { getError(cdSess); } cdSess.SessionINF->DisConnect(); } else { getError(cdSess); } } void getError(ConnectDirectSession& cdSess) { if (cdSess.SessionINF->GetFirstError()) { printf("\nError Message: %s", cdSess.SessionINF->GetMsgID()); printf("\nError Feedback: %d", cdSess.SessionINF->GetFeedBackCode()); printf("\nError RC: %d", cdSess.SessionINF->GetReturnCode()); printf("\nError SUBST: %s\n", cdSess.SessionINF->GetSubstitute()); while(cdSess.SessionINF->GetNextError()) { printf("\nError Message: %s", cdSess.SessionINF->GetMsgID()); printf("\nError Feedback: %d", cdSess.SessionINF->GetFeedBackCode()); printf("\nError RC: %d", cdSess.SessionINF->GetReturnCode()); printf("\nError SUBST: %s\n", cdSess.SessionINF->GetSubstitute()); } }
Method Connect
Description Provides a connection to the Connect:Direct server. Connect() with a void parameter connects to the hostname and port specified in the client configuration file.
DisConnect SendCommand
Disconnects the current session. Sends a Connect:Direct command to the server for processing.
101
Method ReceiveResponse
Description Receives the response from a previously issued command, such as the select statistics command. Retrieves the response from the ReceiveResponse call. Returns the length of the previously received response buffer. Returns a value indicating if outstanding data from the previously issued send command call is available. If the return value is TRUE, call ReceiveResponse again to retrieve more data. Returns the command name of the previously issued send command, such as the submit command. Returns the Process number of a previously issued submit command.
Parameter void
Return Values CD_SUCCESS or CD_FAILURE Pointer to a response buffer. Length of the response buffer from the previously issued call. TRUEIf more data is outstanding. FALSEIf no data is outstanding.
GetResponse GetResponseLength
void void
MoreData
void
GetCommandName
void
Pointer to a command name buffer. Process number of a submit command. -1If no submit command can be found.
GetProcessNumber
void
GetProcessCount
Returns the number of Processes affected by the last send command that issued a delete, change, or flush process.
void
Process number of a submit command that issued a delete, change or flush process. -1If no submit command can be found.
GetCurrentError
Moves the error data pointer to the current error in the list. Moves the error data pointer to the next error in the list.
void
TRUEIf successful FALSEIf no current error exists. TRUEIf successful FALSEIf no more errors are found.
GetNextError
void
GetPreviousError
Moves the error data pointer to the previous error in the list.
void
GetFirstError
Moves the error data pointer to the first error in the list.
void
102
Description Moves the error data pointer to the last error in the list. Retrieves the message of the current error data block. You must call one of the GetXXXXError methods before calling this method in order to retrieve the proper results.
Return Values TRUEIf successful, otherwise FALSE. Return Value: Pointer to a message ID if data block is value.
GetFeedBackCode
Returns the feedback code of the current error data block. Returns the Connect Direct return code. Returns the status.
void
Feedback code.
GetReturnCode
void
One of the valid Connect:Direct return code: 1,4,8,16. Connect:Direct status code. Pointer to a substitution buffer. Return Value: Returns the highest error found in the error chain or -1 on error.
GetStatus
void
GetSubstitute DisplayError
Returns the current substitution buffer associated with the error. Displays the current error chain to an output location.
103
104
Chapter 6
The user exit API functions allow you to write custom programs to use with Connect:Direct.
made with the make_exit_c and make_exit_C make files. The user exit programs are described in the following table:
Program File Open Exit Description Connect:Direct sends a message to this user exit program to open the source or destination file during processing of the copy statement. The File Open Exit opens the source file and identifies the file descriptor. This exit can perform any sort of processing to file names or directory names. It can also redirect the open request to other files as needed. The File Open Exit program (named exit_skeleton in this example) must be owned by root and the setuid bit must be set. Use the following commands: % chown root exit_skeleton % chmod u+s exit_skeleton Security Exit The Security Exit enables you to implement your own security system or provide access to a third-party security system.
105
Description The Statistics Exit is a notification to the user exit program after any record is written to the statistics file. Whenever a statistics record is written to the statistics file, an exact copy is passed to this exit.
recv_exit_msg()
recv_exit_msg_c()
send_exit_file()
send_exit_file_c()
send_exit_msg()
send_exit_msg_c()
106
Following are the return codes for the exit_child_init() or exit_child_init_c() function. Return codes for the function are defined in ndmapi.h.
Description Communications between Connect:Direct and the user exit program were successfully initialized. Communications between Connect:Direct and the user exit program could not be initialized.
int recv_exit_msg( int exit_flag ) int * msg_type, char * recv_buf, int * recv_buf_len
msg_type
Pointer to message
107
Description A pointer to the memory location of the message. The length in bytes of the message to be received.
Following are the return codes for recv_exit_msg()or recv_exit_msg_c(). Return codes for the function are defined in ndmapi.h.
Return Code GOOD_RC ERROR_RC Description The message was received successfully. An error occurred and the message was not received successfully. Possible causes include: Connect:Direct terminated, an invalid value used for the exit_flag parameter, or the receiving buffer not large enough to hold the message received.
exit_flag
fd
File descriptor
Following are the return codes for send_exit_file() or send_exit_file_c(). Return codes for the function are defined in ndmapi.h.
Return Code GOOD_RC Description The file descriptor was received successfully.
108
Description An error occurred and the file descriptor was not sent successfully. Possible causes include: Connect:Direct terminated, an invalid value used for the exit_flag or fd parameters, or the last message sent was not send_exit_msg.
int send_exit_msg int exit_flag int msg_type, char * send_buf, int send_buf_len
msg_type
Pointer to message
send_buf send_buf_len
Following are the return codes for send_exit_msg() or send_exit_msg_c(). Return codes for the function are defined in ndmapi.h.
Return Code GOOD_RC ERROR_RC Description The message was sent successfully. An error occurred and the message was not sent successfully. Possible causes include: Connect:Direct terminated or an invalid value is used for the exit_flag or msg_type parameters.
109
UNIX user ID that will own the file UNIX group ID that will own the file UNIX user name A copy of the Connect:Direct copy control block A copy of the Connect:Direct parsed sysopts structure (the copy control block contains the actual raw version from the process) FILE_OPEN_OUTPUT_REPLY_MSG The user exit program sends a reply message to the Connect:Direct FILE_OPEN_OUTPUT_MSG. The FILE_OPEN_OUTPUT_REPLY_MSG contains: Status value of zero for successful or non zero for failure Status text message (if status value is failure, status text message is included in the error message) Pipe pid (for pipe I/O, the UNIX process ID of the shell process that is performing the shell command for pipe I/O) Actual file name opened (to be used in statistics log messages) If the status value is zero for successful, the user exit program must immediately call send_exit_file() or send_exit_file_c() to send the file descriptor of the opened file to Connect:Direct. FILE_OPEN_INPUT_MSG During the copy statement Process, Connect:Direct sends a FILE_OPEN_INPUT_MSG to the user exit program to open the source file. The FILE_OPEN_INPUT_MSG contains: The open function oflag parameter (for example, O_RDONLY) The open function mode parameter, which controls file permissions UNIX user ID that will own the file UNIX group ID that will own the file UNIX user name A copy of the Connect:Direct copy control block A copy of the Connect:Direct parsed sysopts structure (the copy control block contains the actual raw version from the Process) FILE_OPEN_INPUT_REPLY_MSG This message type is used when the user exit program sends a reply message to the Connect:Direct FILE_OPEN_INPUT_MSG. The FILE_OPEN_INPUT_REPLY_MSG contains: Status value of zero for success or non zero for failure Status text message (if status value is failure, status text message is included in the error message) Pipe pid (for pipe I/O, the UNIX process ID of the shell process that is performing the shell command for pipe I/O) Actual file name opened (used in statistics log messages)
111
GENERATE_MSG Connect:Direct sends a generate message to the user exit program at the start of a session to establish a security environment. The PNODE sends the GENERATE_MSG to the security exit to determine a user ID and security token to use for authentication on the SNODE. The GENERATE_MSG contains: Submitter ID PNODE ID PNODE ID password, if user specified one SNODE ID SNODE ID password, if user specified one PNODE name SNODE name GENERATE_REPLY_MSG The user exit program sends a reply message to Connect:Direct. The GENERATE_REPLY_MSG contains: Status value of zero for success or non zero for failure Status text message (if status value is failure, status text message is included in the error message) ID to use for security context on the SNODE side (may or may not be the same ID as in the generate message) Security token used in conjunction with ID for security context on the SNODE side VALIDATE_MSG Connect:Direct sends a validate message to the user exit program. The SNODE sends the VALIDATE_MSG to the security exit to validate the user ID and security token received from the PNODE. The VALIDATE_MSG contains: Submitter ID PNODE ID PNODE ID password, if user specified one SNODE ID
112
SNODE ID password, if user specified one PNODE name SNODE name ID to use with security token Security token (password, PASSTICKET, or other security token) VALIDATE_REPLY_MSG The user exit program sends a reply message to the Connect:Direct VALIDATE_MSG. The VALIDATE_REPLY_MSG contains: Status value of zero for success or non zero for failure Status text message (if status value is failure, status text message is included in the error message) ID used for security context Security token to use in conjunction with ID for security context
The log files are located in the installed (d_dir) working directory:
.../d_dir/work/cd_node
113
114
Glossary
A
Application Programming Interface (API)
A library of function calls that enables End User Applications (EUAs) to interact with Connect:Direct.
C
Client
A program that makes requests of the Connect:Direct server and accepts the server's responses.
Connect:Direct
The family of data transfer software products that distributes information and manages production activities among multiple data centers.
115
Glossary
Connect:Direct Node
Any computer/workstation running Connect:Direct.
Connect:Direct Process
A series of statements, which can be predefined and stored in a directory, submitted through the API to initiate Connect:Direct for UNIX activity. Examples of Process functions are copying files and running jobs.
D
daemon
The long-running process that provides a service to a client. The PMGR is the Connect:Direct for UNIX daemon.
Diagnostic Commands
Connect:Direct commands that assist in the diagnosis of Connect:Direct software problems.
E
End User Application (EUA)
An application program developed by an end user to accomplish a particular task.
Execution Queue
A logical queue in the TCQ. A Process in the Execution Queue can be transferring data to or from a remote Connect:Direct node or it can be waiting for a connection to the remote Connect:Direct node before it can perform its tasks.
116
Glossary
F
File Agent
An application program and component of Connect:Direct. It scans specified directories searching for the presence of a file. When a file appears in a watched directory, Connect:Direct either submits a Process or performs the action specified by the rules for the file.
H
Hold Queue
A logical queue in the TCQ. Processes in the Hold Queue are waiting for operator intervention before they move to the Wait Queue for scheduling.
M
Monitoring Commands
Connect:Direct commands that allow you to display information from the statistics file and the TCQ about Connect:Direct Process execution results.
O
Operational Control Commands
Connect:Direct commands that allow you to submit a Process, change specific characteristics of a Process in the TCQ, remove executing and nonexecuting Processes from the TCQ, and stop Connect:Direct.
P
Process Manager (PMGR)
The long-running Connect:Direct server that initializes the Connect:Direct software, accepts connection requests from Connect:Direct APIs and remote Connect:Direct nodes, creates Command Managers and Session Managers, accepts requests from Command Managers and Session Managers where centralized Connect:Direct functions are required, and terminates Connect:Direct software execution.
117
Glossary
S
Session
A connection between two Connect:Direct nodes.
118
Glossary
T
TCQ Status Value
A two-letter code assigned to a Process by Connect:Direct when the Process is placed on the TCQ. The status of a Process can be examined with a select process command.
Timer Queue
A logical queue in the TCQ. Processes on the Timer Queue are waiting for a start time before they move to the Wait Queue for scheduling.
W
Wait Queue
A logical queue in the TCQ. Processes on the Wait Queue are waiting on a connection to or from the remote Connect:Direct node.
119
Glossary
120
Index
Symbols
&symbolic name parameter, submit command 35 class parameter change process command 39 submit command 30 CLI, description 9 cmd_id parameter 99 cmd_name parameter 99 cmd_text parameter 98 cmgr parameter 60 CMGR, description 8 comm parameter 60 Command and the TCQ 63 change process 14, 27, 37 conventions 29 delete process 14, 27, 40 fg 26 flush process 14, 27, 42 for TCQ 13 foreground 26 operational control 27 select process 14, 45, 48 select statistics 14, 52 stop 14, 27, 44 stopping the CLI 27 submit 14, 30 syntax 27 trace 14, 59 Command Line Interface (CLI) description 23 starting 23 terminating 27 using 23 Command line interface, overview 9 Command manager, overview 8 Commands ndmmsg 74 ndmxlt 70
A
API function calls connecting to the Connect:Direct server 92 exit_child_init() 106 ndmapi_connect() 93 ndmapi_disconnect() 94 ndmapi_recvresp() 94 ndmapi_sendcmd() 98 overview 89 recv_exit_msg() 107 send_exit_file() 108 send_exit_msg() 109 API, description 9
C
C program, compile command 90 C++ program, compile command 90 cdcustrpt utility 84 cdsacomp 76 cfgCheck utility 83 arguments 83 change process command class parameter 39 description 27, 37 format 38 hold parameter 39 newsnode parameter 39 overview 37 pname parameter 38, 42, 45, 48, 52, 53 pnumber parameter 38, 42, 46, 48, 53 prty parameter 40 release parameter 40 snode parameter 38, 43, 46, 49, 56 submitter parameter 39, 43, 47, 50, 58
121
Index
Compile command for a C++ program AIX 90, 91 HP 90, 91 Linux 90, 91 LinuxS390 91 Sun 90, 91 Compression Utility 76 Configuration Checking Utility arguments 83 Configuration Reporting Utility Base installation 84 cdcustrpt 84 Secure+ Option 86 SwiftNet 87 Connect:Direct API function calls 89 commands 23 concepts 12 function calls 89 Connecting to the server, with API function calls 92 Creating translation tables 70
E
-e nn parameter, direct command 25 Error numbers, generated by ndmxlt 73 error parameter ndmapi_connect() function 93 ndmapi_recvresp() function 95 ndmapi_sendcmd() function 98 Error responses 92 ERROR_RC return code exit_child_init() function 107 recv_exit_msg() function 108, 109 Establishing a server connection, using API function 92 EX status value 66
D
Data responses, for API commands 92 Definition local node 12 remote node 12 delete process command 27, 40 description 40 pname parameter 41 pnumber parameter 42 snode parameter 42 submitter parameter 42 Description API 9 CLI 9 CMGR 8 network map 14 PMGR 7 TCQ 13 user authorization 15 destfile parameter, select statistics command 52 direct command parameters, -e nn 25 parameters, -h 26 parameters, -n name 25
Execution queue 65 Exit log files 113 file_exit.log 113 stat_exit.log 113 exit_child_init() function 106 description 106 parameters, logfile 107 return codes, ERROR_RC 107 return codes, GOOD_RC 107 exit_flag parameter recv_exit_msg() function 107 exit_flag parameter, send_exit_file() function 108 exit_msg parameter recv_exit_msg() function 109
F
-f parameter, for ndmmsg command 75 -ffiller parameter 71 File open exit description 105 message types 110 file_exit.log 113
122
Index
filename parameter 30 Files, message 73 flush process command 27, 42 description 42 Foreground, moving a CLI process 26 Function calls exit_child_init() 106 ndmapi_connect() 93 ndmapi_disconnect() 94 ndmapi_recvresp() 94 ndmapi_sendcmd() 98 ndmapi-sendcomd() 98 overview 89 recv_exit_msg() 107 send_exit_file() 108 send_exit_msg() 109
list, parameter value 29 Local node definition of 12 in network map 14 logfile parameter exit_child_init() function 107
M
-m parameter 71 Managing Processes 63 Manipulating Processes in the TCQ 63 max.age, parameter 16 maxdelay parameter 31 Message files, overview 73 message ID format 73 message record format 74 Message utility message ID format 73 message record format 74 overview 73 Modifying translation tables 70 Moving a CLI process foreground 26 msg_type parameter, recv_exit_msg() function 107 msg_type parameter, send_exit_msg() function 109
G
Generic parameter value 29 GOOD_RC return code exit_child_init() function 107 recv_exit_msg() function 108, 109
H
-h parameter, for direct 26 HC status value 68 HE status value 68 HI status value 68 HO status value 68 hold parameter change process command 39 submit command 30 Hold queue 67 HR status value 67, 68 HS status value 68
N
-n name parameter, direct command 25 ndm_hostname parameter 93 NDM_NO_ERROR return code ndmapi_connect() function 94, 97, 99 ndm_portname parameter 94 ndmapi_connect() function description 93 error parameter 93, 95, 98 format 93 ndm_hostname parameter 93 NDM_NO_ERROR 94, 97, 99 ndm_portname parameter 94 ndmapi_disconnect() function, description 94
I
immediate parameter 45 informational responses, API 92
L
-l parameter, for ndmmsg command 75
123
Index
ndmapi_recvresp() function description 94 example 98 resp_buffer parameter 95, 96, 97 resp_length parameter 95 resp_moreflag parameter 97 TRUNCATED return code 97 ndmapi_sendcmd() function 98 cmd_id parameter 99 cmd_name parameter 99 cmd_text parameter 98 description 98 resp_moreflag parameter 98 ret_data parameter 99 sendcmd_data parameter 99 ndmmsg description 74 message ID format 73 message id format 73 message record format 74 overview 73 parameter, -l 75 parameter, -s 75 parameters, -f 75 using to display message text 73 ndmxlt creating translation tables 70 errors generated 73 modifying translation tables 70 ndmxlt command parameters -ffiller 71 -m 71 -ooutputfile 70 -rradix 71 -ssourcefile 70 ndmxlt utility, and the copy statement 72 Network map file description 14 newname parameter, submit command 31 newsnode parameter, change process command 39
P
-p nnnnn parameter, direct command 25 pacct parameter 31 Parameters, scheduling for the TCQ 64 PE status value 66 pmgr parameter, trace command 61 PMGR, description 7 pname parameter change process command 38, 42, 45, 48, 53 delete process command 41 pnodeid parameter, submit command 31 pnumber parameter change process command 38, 42, 46, 48, 53 delete process command 42 Process restart, overview 15 Process statements, listed 12 Process, samples 17 prty parameter change process command 40 submit command 31
Q
queue parameter 46, 48 Queues execution 65 hold 67 timer 67 wait 66 quiesce parameter 45
R
-r parameter, direct command 26 reccat parameter 53 recids parameter 54 recv_buf_len parameter 108 recv_exit_msg() function description 107 ERROR_RC return code 108, 109 exit_flag parameter 107, 108, 109 GOOD_RC return code 108, 109 msg_type parameter 107, 109
O
-ooutputfile parameter, ndmxlt 70 Operational control commands 27
124
Index
recv_buf_len parameter 108 send_buf parameter 108 release parameter 40 Remote node definition of 12 in network map 14 Remote node information record creating 19 resp_buffer parameter 95, 96, 97 resp_length parameter 95 resp_moreflag parameter ndmapi_recvresp() function 97 ndmapi_sendcmd() function 98 ret_data parameter 99 retain parameter 32 Return codes ERROR_RC, exit_child_init() function 107 ERROR_RC, recv_exit_msg() function 108, 109 GOOD_RC, exit_child_init() function 107 GOOD_RC, recv_exit_msg() function 108, 109 NDM_NO_ERROR, ndmapi_connect() function 94, 97, 99 TRUNCATED, ndmapi_recvresp() function 97 -rradix parameter, for ndmxlt utlity 71
select statistics command 52 description 52 format 52 reccat parameter 53 recids parameter 54 required parameters 52 startt parameter 57 stopt parameter 57 send_buf parameter recv_exit_msg() function 108 send_exit_msg() function 109 send_buf_len parameter 109 send_exit_file() function description 108 format 108 send_exit_msg() function 109 description 109 format 109 send_buf parameter 109 send_buf_len parameter 109 sendcmd_data parameter 99 Session manager description 8 overview 8 Shell script, samples 17 SMGR 8 trace command 61 snode parameter change process command 38, 43, 46, 49, 56 delete process command 42 select process command 47, 50 submit command 33 snodeid parameter 34 srcfile parameter select statistics command 57 -ssourcefile parameter 70 Standalone Batch Compression 76 startt parameter select statistics command 57 submit command 35 stat_exit.log 113 statistics exit description 106 message types 110
S
-s parameter direct command 24 ndmmsg command 75 sacct parameter 32 Samples Processes 17 shell scripts 17 Scheduling Connect:Direct activity 64 retain parameter 64 startt parameter 64 Security exit description 105 message types 112 select process command 45, 48 description 45, 48 queue parameter 46, 48 snode parameter 47, 50
125
Index
Status values hold queue 68 overview 64 wait queue 66 step parameter 45 Sterling Control Center 10 stop command 27, 44 description 44 immediate parameter 45 quiesce parameter 45 step parameter 45 Stopping the CLI 27 stopt parameter 57 submit command &symbolic name parameter 35 class 30 description 30 filename parameter 30 hold 30 newname parameter 31 parameter, maxdelay 31 parameter, prty 31 parameters, pacct 31 pnodeid parameter 31 retain parameter 32 sacct parameter 32 snode parameter 33 snodeid parameter 34 startt parameters 35 submitter parameter change process command 39, 43, 47, 50, 58 delete process command 42 Submitting a Process, defined 27
TCQ, description 13 Timer queue 67 trace command 59 cmgr parameter 60 comm parameter 60 description 59 format 59 pmgr parameter 61 smgr parameter 61 Translation table utility and the copy statement 72 creating translation tables 70 error numbers 73 modifying translation tables 70 Transmission Control Queue and commands 63 hold parameter 64 overview 63 status values in hold queue 68 Transmission Control Queue, process progression 65 TRUNCATED return code 97
U
User authorization information file, description 15 User exits file open exit 105 file open exit message type 110 security exit 105 security exit types 112 statistics exit 106 statistics exit messsage 110 Utilities ndmxlt and the copy statement 72 ndmxlt, creating translation tables 70 ndmxlt, modifying translation tables 70 translation table 70 translation table and the copy statement 72 translation table, modifying translation tables 70
T
-t nn parameter, direct command 25 TCQ and commands 63 hold parameter 64 overview 63 Process progression 65 retain parameter 64 startt parameter 64 TCQ status values hold queue 68 wait queue 66
V
Validating configuration files 83 view process, command 27, 45
126
Index
W
WA status value 66 Wait queue 66 WC status value 66, 67 Wildcard facility 29 WR status value timer queue 67 wait queue 66 WS status value 66, 67
X
-x parameter, direct command 25 XXLT001I error number, translation table 73 XXLT002I error number, translation table 73 XXLT003I error number, translation table 73 XXLT004I error number, translation table 73 XXLT005I error number, translation table 73 XXLT006I error number, translation table 73 XXLT007I error number, translation table 73 XXLT008I error number, translation table 73
Z
-z parameter, direct 26
127
Index
128