Sterling Connect:Direct for UNIX User Guide Version 4.
Sterling Connect:Direct for UNIX User Guide Version 4.
Note Before using this information and the product it supports, read the information in “Notices” on page 83. This edition applies to version 4.1 of IBM Sterling Connect:Direct for UNIX and to all subsequent releases and modifications until otherwise indicated in new editions. © Copyright IBM Corporation 1999, 2013. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents Chapter 1. Controlling and Monitoring Processes . . . . . . . . . . . . . . 1 Overview of the Command Line Interface . . . Starting the CLI . . . . . . . . . . . Stopping the CLI . . . . . . . . . . . CLI Commands . . . . . . . . . . . CLI Job Control . . . . . . . . . . . CLI History Commands . . . . . . . . Overview of Sterling Connect:Direct Commands Submitting a Process. . . . . . . . . . Changing Process Parameters . . . . . . Deleting a Process from the TCQ . . . . .
iv Sterling Connect:Direct for UNIX: User Guide
Chapter 1. Controlling and Monitoring Processes Overview of the Command Line Interface The Command Line Interface (CLI) enables you to submit Sterling Connect:Direct® Processes and commands from a native command line environment. You can also use the Sterling Connect:Direct Browser User Interface to perform some of these tasks. Starting the CLI Procedure 1.
Option Description Value -P Identifies the custom string to use at the command line prompt. text string Up to 32 characters. Sample Command Entry $ direct -PNewPrompt $ direct -P”Test CD on Medea” If the prompt string includes spaces or special characters, enclose it in single or double quotation marks. The prompt string can also be specified in the ndmapi.cfg file. If a prompt string is specified on the command line and in the ndmapi.cfg file, -P takes precedence.
Option Description Value Sample Command Entry -e nn Defines the error level above which the CLI automatically exits. If the returned error code is greater than the error level specified, the CLI automatically exits. 0 | 4 | 8 | 16 $ direct -e 16 Valid values in the error level code are: 0—Indicates successful completion. Use this command within shell 4—Indicates warning. scripts.
enables you to edit the text of saved Processes, issue UNIX commands, and resolve Process errors without exiting and reentering the CLI. Use the following commands to switch the CLI Process: v Press the suspend character (Control-Z) to stop or suspend the CLI Process. v Issue the fg command to move the CLI Process to the foreground. Note: If you experience problems with job control, contact your system administrator for suggestions on additional UNIX commands to use.
Abbreviations for Common Sterling Connect:Direct Commands The following table lists valid abbreviations for commonly used parameters for Sterling Connect:Direct commands: Parameter Abbreviation detail det quit q recids rec release rel pname pnam, pna pnumber pnum sunday sun monday mon tuesday tue wednesday wed thursday thu friday fri saturday sat today tod tomorrow tom Restricting the Scripts and UNIX Commands Users Can Execute System administrators and other network operatio
v When typing commands, type the entire command name or type the first three characters or abbreviate specific parameters. Refer to “Abbreviations for Common Sterling Connect:Direct Commands” on page 5for a list of abbreviations. v Do not abbreviate Process statements and parameters. v File names, group names, user IDs, and passwords are variable length strings and can be any length. v A Sterling Connect:Direct node name is 1–16 characters long.
Parameter Description Values class The node-to-node session on which a Process can execute. A Process can execute on the class specified or any higher session class. The default class is specified as the sess.default parameter of the local.node record in the initialization parameters file. 1|n crc hold Determines if crc checking is performed. This parameter overrides settings in the initialization parameter, the network map, and the Process.
Parameter Description Values notify username@hostname or user@localhost The user e-mail to receive Process completion messages. This parameter uses the rmail utility available in the UNIX System V mail facility to deliver the completion messages. Note: Sterling Connect:Direct does not validate the e-mail address or user ID supplied to the notify parameter. Invalid e-mail addresses and failed E-mail attempts are handled according to the local mail facilities configuration.
Parameter Description Values snode Identifies the name of the secondary node. Setting this value overrides the snode value in the Process statement. The snode parameter is required either on the submit command or Process statement. name | host name | nnn.nnn.nnn.nnn or nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn:nnnn[;port name | nnnnn]] name—Specifies the node name of the remote node. The secondary node name corresponds to an entry in the network map file.
Parameter Description Values snodeid Specifies security user IDs and security passwords on the SNODE. The snodeid subparameters can contain one or more alphanumeric characters. id [,pswd [,newpswd]] If Sterling Connect:Direct finds that a Process has no snodeid parameter or defines a snodeid parameter and the initialization parameter proxy.attempt is set to y, then any password specified on the snodeid parameter is ignored. A proxy user record is a remote user record in the userfile.
Parameter Description Values startt Identifies the date, day, and time to start the Process. Sterling Connect:Direct places the Process in the Timer queue in WS (Waiting for Start Time) status. The date, day, and time are positional parameters. If you do not specify date or day, a comma must precede time. [date | day] [,hh:mm:ss [am | pm]] Do not code the startt parameter when you specify retain=initial.
Parameter Description Values tracel level = 0 |1 | 2 | 4 Specifies the level of trace to perform for a Process. Tracing by Process can be turned on in the submit command or as part of the Process snode | pnode definition. file=name If you identify the snode or pnode immediately after the trace level definition, the level—Specifies the level of detail displayed in the trace output. The default is 4. trace level is turned on for all Processes submitted to and from the node identified.
Example - Submit a Process and Turn On Tracing The following command submits the Process named copy.cdp: submit file=copy.cdp tracel=4 pnode; Because tracel is specified and the pnode parameter is included, an SMGR and COMM full trace is performed on the Process. Trace information is written to the default file SMGR.TRC. Changing Process Parameters The change process command modifies specified parameters for a nonexecuting Process.
Parameter Description Value snode Locate the Process to be changed by the secondary node name. This parameter can be used to specify a specific remote node, a generic value for matching remote node names (using pattern matching), or a list of multiple remote node names. remote node specification | generic | (list) The secondary node name typically contains the 1–16 character remote Sterling Connect:Direct node name, but can be any string up to 256 alphanumeric characters long.
Parameter Description Value hold Moves the Process to the Hold yes | no | call or Wait queue. yes—Places the Process in the Hold queue in HO status until it is released by another change process command. no—Places the Process in the Wait queue in WC (Waiting for Connection) status; the Process executes as soon as resources are available. This is the default.
You select the Process to delete by Process name, Process number, secondary node name, submitter, or any combination of the search criteria parameters. Specify at least one of the following search criteria parameters: Parameter Description Value pname Identify the Process to delete name | generic | (list) by Process name. name—Specifies the Process name up to 8 The Process name is limited alphanumeric characters long.
The following command deletes all nonexecuting Processes submitted by user ID cduser on node dallas: delete process submitter=(dallas, cduser); Removing a Process from the Execution Queue The flush process command removes Processes from the Execution queue. You select the Process to remove by Process name, Process number, secondary node name, submitter, or any combination of the search criteria parameters.
Parameter Description Value submitter Locate the Processes to remove by the node specification (the Sterling Connect:Direct node name) and user ID of the Process owner. (node specification, userid) | generic | (list) node specification, userid—Specifies the node specification (the Sterling Connect:Direct node name) and user ID. generic—Specifies a nonspecific value for node specification and user ID.
You can specify the force, immediate, quiesce, or step parameters with the stop command. Note: The force parameter is required when running Sterling Connect:Direct with the LU6.2 feature on any supported platform other than AIX. Following are the parameters for the stop command: Parameter Description force Forcibly terminates Sterling Connect:Direct and returns control to the operating system. immediate Begins an immediate, but orderly shutdown of all activity and terminates Sterling Connect:Direct.
Parameter Description Value pname Locate the Process to view by Process name. name | generic | (list) The Process name is limited to 8 characters on Sterling Connect:Direct for Microsoft Windows and Sterling Connect:Direct for z/OS. name—Specifies the Process name, up to 8 alphanumeric characters. generic—Specifies a nonspecific value for the Process name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more pname strings.
Parameter Description Value status Specifies the Processes to be viewed by Process status. If you do not specify a status value, information is generated for all status values. EX | HC | HE | HI | HO | HR | HS | PE | WC | WR | WS | (list) EX (Execution)—Specifies to select Processes from the Execution queue. HC (Held for Call)—Specifies to select Processes submitted with hold=call. HE (Held due to Error)—Specifies to select Processes held due to a connection error.
Parameter Description Value submitter Locate the Processes to view by the node specification (the Sterling Connect:Direct node name) and user ID of the Process owner. The length of this parameter is unlimited. (node specification, userid) | generic | (list) node specification, userid—Specifies the node specification (the Sterling Connect:Direct node name) and user ID. generic—Specifies a nonspecific value for node specification and user ID.
Parameter Description Value queue Specifies the Processes to be all | exec | hold | wait | timer selected by the specified queue names. The default is all—Selects Processes from all queues. this is the default. all. exec—Selects Processes from the Execution queue. hold—Selects Processes from the Hold queue. timer—Selects Processes from the Timer queue. wait—Selects Processes from the Wait queue. snode Locate the Process by the secondary node name.
Parameter Description Value status Specifies the Processes to be selected by Process status. If you do not specify a status value, information is generated for all status values. EX | HC | HE | HI | HO | HR | HS | PE | WC | WR | WS | (list) EX (Execution)—Specifies to select Processes from the Execution queue. HC (Held for Call)—Specifies to select Processes submitted with hold=call. HE (Held due to Error)—Specifies to select Processes held due to a connection error.
Parameter Description Value submitter Locate the Processes to select by the node specification (the Sterling Connect:Direct node name) and user ID of the Process owner. The length of this parameter is unlimited. (node specification, userid) | generic | (list) node specification, userid—Specifies the node specification (the Sterling Connect:Direct node name) and user ID. generic—Specifies a nonspecific value for node specification and user ID.
Determining the Outcome of a Process The select statistics command is used to examine Process statistics from the Sterling Connect:Direct statistics file. The type of information in the statistics report includes copy status and execution events. The search criteria provide flexibility in selecting information you want to display. The parameters used with the select statistics command determine search criteria and the form in which the information is presented.
Parameter Description Value pname Locate the statistics to select by Process name. name | generic | (list) The Process name is limited to 8 characters on Sterling Connect:Direct for Microsoft Windows and Sterling Connect:Direct for z/OS. name—Specifies the Process name, up to 8 alphanumeric characters. generic—Specifies a nonspecific value for the Process name. This generic value, containing pattern-matching characters, evaluates to a list of zero or more pname strings.
Parameter Description Value CTRM—Child Process terminated. CUKN—Child Process unknown status. CXIT—Child Process exited. DELP—The delete Process command issued. FLSP—The flush Process command issued. FMRV—Error occurred in function management. information receive operation. FMSD—Error occurred in function management. information send operation. GPRC—Error occurred while getting Process. IFED—The if statement ended. LSST—The record ID of a step on the local node. LIEX—License expired.
Parameter Description Value PSTR—Process started. QCEX—A Process moved from another queue to the EXEC queue. QCWA—A Process moved from another queue to the WAIT queue. QCTI—A Process moved from another queue to the TIMER queue. QCHO—A Process moved from another queue to the HOLD queue. RJED—The run job ended. RNCF—Remote node connection failed. RSST—The record ID of a step on the remote node. RTED—The run task ended. RTSY—Run task restarted. Resyncing with run task that was executing.
Parameter Description Value UNKN—Unknown command issued. USEC—Security check for user ID failed. USMG—Sterling Connect:Direct is shutting down. XCMM—Command manager (CMGR) messages. XCPR—Copy receive. XCPS—Copy send. XIPT—Communication errors. XLKL—Low-level TCQ record locking errors. XMSG—Message sent to user exit. XPAE—Parsing error occurred when a Process or command was submitted. XPAM—Parsing error occurred when a Process or command was submitted. XPMC—Process manager (PMGR) connection error messages.
Parameter Description Value snode Locate the statistics file record by the secondary node name. This parameter can be used to specify a specific remote node, a generic value for matching remote node names (using pattern matching), or a list of multiple remote node names. remote node specification | generic | (list) Selects statistics based on a source file name. This parameter can be abbreviated as srcf. srcf=/path/file name remote node specification—Identifies a specific remote node name.
Parameter Description Value stopt Specifies that Sterling Connect:Direct searches for statistics records up to and including the designated date, day, and time positional parameters. If you do not specify date or day, a comma must precede time. [date | day] [, hh:mm:ss [am|pm]] date—Specifies the day (dd), month (mm), and year (yy), which you can code as mm/dd/yyyy or mm-dd-yyyy. If you only specify date, the time defaults to 00:00:00. The current date is the default. day—Specifies the day of the week.
Generating a Summary Report for a Process You can use the select statistics command to generate a summary report for a Process. The following command generates summary statistics for Process number 9: sel stat pnumber=9 detail=no startt=(08/10/2008); The report consists of all records from August 10, 2008.
Parameter Description Value cmgr To trace the Command Manager. level=0 |1 | 2 | 4 file=name level—Specifies the level of detail displayed in the trace output. The default is 4. 0—Terminates the trace. 1—Is the basic level that provides function entry and function exit. 2—Includes level 1 plus function arguments. 4—Enables a full trace. Basic diagnostic information, such as values of internal data structures at key points in the execution flow, are displayed.
Parameter Description Value pmgr To trace the Process Manager. level=0 |1 | 2 | 4 file=name level—Specifies the level of detail displayed in the trace output. The default is 4. 0—Terminates the trace. 1—Is the basic level that provides function entry and function exit. 2—Includes level 1 plus function arguments. 4—Enables a full trace that provides basic diagnostic information, such as values of internal data structures at key points in the execution flow.
trace smgr pnode tnode=ath3500ry level=2 file=Smgp.trc; A partial sample trace output is illustrated in the following section. A trace identifies the Process ID and the function, the month and day, and the time in microseconds. The first column contains the Process ID. Column two indicates the month and day in the form of MM/DD. Column three indicates the time in the form of HH:MM:SSSS. The last column indicates the function. An arrow pointing to the right indicates the function was entered.
Chapter 2. Process Queuing Overview of the Transmission Control Queue The TCQ controls Process execution as Sterling Connect:Direct operates. After you submit a Process, it is stored in the TCQ. The TCQ consists of four queues: Execution, Wait, Timer, and Hold. After you submit a Process, you can monitor the status, modify specific characteristics, and stop execution by using the appropriate commands.
Scheduling Parameter Queue Comments retain=initial Hold A copy of the Process remains in the Hold queue and executes every time the Process Manager is initiated. retain=yes and hold=no or hold=call Hold A copy of the Process remains in the Hold queue to be executed when released. hold=yes Hold You can execute the Process by specifying the change process command with the release parameter. hold=no Wait (if no other The default for hold is no.
The Execution Queue Processes are placed in the Execution queue after Sterling Connect:Direct connects to the remote node. Processes normally come from the Wait queue, but also can be placed in the Execution queue by a submit command with maxdelay=0 specified. Processes in the Execution queue can be in execution (EX) status or pending execution (PE) status. Processes with EX status are exchanging data between two Sterling Connect:Direct nodes.
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.
The Timer Queue Processes are placed in the Timer queue by a submit command with the startt parameter specified. Processes in the Wait for Start Time (WS) status are waiting for the start time to arrive before moving to the Wait queue.
Processes 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.
Chapter 3. Sterling Connect:Direct Utilities Introduction to Translation Tables Sterling Connect:Direct translates data from one character set code to a different character set code, such as from ASCII to EBCDIC, based on a character translation table in the d_dir/ndm/xlate directory. Sterling Connect:Direct provides a default character translation table for use during file transfer operations or you can modify this table using the utility program called ndmxlt. Creating a Translation Table 1.
Compiling a Translation Table Using the ndmxlt Utility Before you begin You can create or modify a translation table tailored to your requirements with the ndmxlt utility program. To invoke the ndmxlt utility, type the following command at the UNIX prompt: $ ndmxlt -ssourcefile -ooutputfile [ -rradix] [ -ffiller] -mxlatefile The parameters for the ndmxlt command are listed in the following table: Parameter Description Values -ssourcefile The path and file name of the translation table source file.
3. Add the following lines to the bottom of the table. It should look like the table in “Creating a Translation Table” on page 43when you have added this information. # # Change the lowercase characters to uppercase. offset=61 C1 C2 C3 C4 C5 C6 C7 C8 C9 D1 D2 D3 D4 D5 D6 D7 D8 D9 E2 E3 E4 E5 E6 E7 E8 E9 4. Copy the modified file to cd_dir/ndm/src and name it UpperCaseEBC.sxlt. 5. Compile the new translation table using the following syntax: ndmxlt -s../src/UpperCaseEBC.sxlt -oUpperCaseEBC.xlt 6.
To specify a customized table for data translation, include the following sysopts subparameter in the copy statement, where pathname/filename identifies the translation table: copy from file=filename to file=filename sysopts=":xlate.tbl=pathname/filename:" Refer to the UNIX section of the IBM® Sterling Connect:Direct Processes Web site at http://www.sterlingcommerce.com/documentation/processes/ processhome.html for additional details concerning translation table specification with a copy statement.
xxx is a 3-character Sterling Connect:Direct component identifier nnn is a 3-digit decimal number I is the standard, though not required, suffix Message File Record Format The following example shows the format of the message file record. Each record can be up to 4K bytes long. Optional parameters and values are in brackets. message id [long.text detailed message explanation] [mod.name issuing module name] short.
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).
Using the Standalone Batch Compression Utility Before you begin To invoke the standalone batch compression utility (cdsacomp), type the following command at a UNIX prompt: cdsacomp Following are the parameters for the cdsacomp utility: Parameter Description Values -m Specify which mode to use: precompress or decompress. This argument is required. compress | decompress The default is compress. -i Specify the input file to precompress or decompress. This argument is required.
Parameter Description Values -p Use this option to specify codepages for file conversion. Default is no codepage translation. source codepage, destination codepage This parameter is mutually exclusive with -xlate. -d Specify the datatype of the file. text | binary | VB When you use “-m compress”, the datatype values result in the following: The default is text.
Parameter Description Values -a Use this option to replace zero-length records with a single, blank character. y|n This parameter is valid only when you specify the following: “-d text” and “-m compress”. y—yes n—no The default is y. Specify n if the data is copied to an i5OS or mainframe node. -h Use this option to display online help for No values are available for the utility. this parameter. Example—Precompress a Text File In this example, the source file is a text file named source.
cdsacomp -m -d -i -o -x decompress text compressed.file dest.file /home/cd/ndm/xlate/def_recv.xlt Examples—csdacomp Command Help Requesting a summary of cdsacomp command parameters and help options: cdsacomp -h Example—Decompress a File on the Remote Node During the Copy Step The “precomp=yes” parameter is used when the file was compressed by the cdsacomp utility prior to this Process. The file is transferred by this Process as a pre-compressed file.
Validate Configuration Files When you manually edit any of the five text-based Sterling Connect:Direct configuration files, the Configuration Checking Utility (cfgcheck) enables you to validate these files offline. The following files can be validated using this utility: userfile.cfg, initparm.cfg, netmap.cfg, ndmapi.cfg, and sysacl.cfg. Note: The Strong Access Control File (sysacl.cfg) will be validated only when the user running the Configuration Checking Utility is a root user.
v Sterling Connect:Direct Secure Plus for UNIX v Sterling Connect:Direct for SWIFTNet for UNIX During the Sterling Connect:Direct installation, cdcustrpt is installed in the /etc/ directory.
########################################################################### ####### Connect:Direct for UNIX 4.0.
The following example shows an excerpt from a sample report: ===== Begin: Secure+ parameters ===== ========================================= All secure+ nodes: ************************************************************** * Secure+ Command Line Interface * * Connect:Direct for UNIX v4.0.00 * *------------------------------------------------------------* * Copyright (c) 1999, 2008 Sterling Commerce Inc. * * All Rights Reserved.
Log.MaxVersions="5" [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/" Chapter 3.
58 Sterling Connect:Direct for UNIX: User Guide
Chapter 4. Writing Custom Programs Introduction to Writing Custom Programs The Sterling Connect:Direct Application Programming Interface (API) allows you to write custom programs in either C or C++ to use with Sterling Connect:Direct.
Platform C++ Compile Command 64-bit /opt/SUNWspro/bin/CC -xarch=generic64 -DBSD_COMP -I../include -o sdksample sdksample.C ../lib/ndmapi64.a -L/usr/ucblib/sparcv9 -L/usr/lib/sparcv9 -L/usr/ucblib/amd64 -lsocket -lrpcsoc -lnsl -lelf -ldl -R/usr/ucblib/sparcv9 -R/usr/ucblib/amd64 HP 32-bit /opt/aCC/bin/aCC -AA -I../include -o sdksample sdksample.C ../lib/ndmapi.a -lrpcsoc -lnsl -ldld -Wl,+s 64-bit /opt/aCC/bin/aCC -AA +DD64 -I../include -o sdksample sdksample.C ../lib/ndmapi64.
Platform C Compile Command HP 32-bit /opt/ansic/bin/cc -I../include -o apicheck apicheck.c ../lib/ndmapi.a -lrpcsoc -lnsl -ldld -Wl,+s -lcl -lstd_v2 -lCsup_v2 64-bit /opt/ansic/bin/cc +DD64 -I../include -o apicheck apicheck.c ../lib/ndmapi64.a -L/usr/lib/pa20_64 -lnsl -ldld -Wl,+s -lcl -lstd_v2 -lCsup_v2 HP-Itanium 32-bit /opt/ansic/bin/cc -I../include -o apicheck apicheck.c ../lib/ndmapi.a -lrpcsoc -lnsl -ldld -Wl,+s -lcl -lstd_v2 -lCsup -lunwind 64-bit /opt/ansic/bin/cc +DD64 -I..
C++ Function C Function Description ndmapi_sendcmd() ndmapi_sendcmd_c() Sends commands to Sterling Connect:Direct. You must provide the command text. The resp_moreflag is a pointer to the flag indicating that more responses are pending for the executed command. Invoke ndmapi_recvresp_c() for C programs or ndmapi_recvresp() for C++ programs to retrieve the extra responses.
from the commands. Control returns to the application when the connection is established and Sterling Connect:Direct is ready for the first API request or when an error condition is set.
Receiving Responses Using ndmapi_recvresp() or ndmapi_recvresp_c() Use ndmapi_recvresp() or ndmapi_recvresp_c() to receive responses that are associated with a previous command sent from the application.
Parameter Description Value DDS1—Destination disposition 1 DDS2—Destination disposition 2 DDS3—Destination disposition 3 DESC—Sterling Connect:Direct administrator description DFIL—Destination file DMSG—Destination message ID DNVL—Destination number of volumes DRCW—Records written DRUX—RUs received DVOL—Destination volume array ECMP—Extended compression ON or OFFFROM—Copy sending node LCCD—Local completion code LCLP—Local IP address and port number LKFL—Link fail LMSG—Local message ID LNOD—Local node MSGI
Parameter Description Value PNOD—PNODE PNUM—Process number PPMN—PDS member name PRTY—Priority QUEU—Queue RECC—Record category RECI—Record ID RETA—Retain Process RMTP—Remote IP address and port number RSTR—Process restarted RUSZ—RU Size SACC—SNODE account SBID—Submitter node ID SBND—Submitter node name SBYR—Bytes read SBYX—Bytes sent SCMP—Standard compression SCOD—Source completion code SDDY—Schedule date SDS1—Source disposition 1 SDS2—Source disposition 1 SDS2—Source disposition 2 SDS3—Source disposition
Parameter Description Value STAT—Process status SNOD—SNODE SNVL—Source number of volumes SOPT—SYSOPTS record SRCR—Records read SRUX—RUs sent STIM—Schedule time STOP—Stop time of the event SUBM—Submitter ID SUBN—Submitter node SUMM—Summary output selector SVOL—Source volume array TIME—Submit time XLAT—Translation 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.
Sending a Command to Sterling Connect:Direct Using ndmapi_sendcmd() or ndmapi_sendcmd_c() Use ndmapi_sendcmd() or ndmapi_sendcmd_c() to allow a command to be sent to a Sterling Connect:Direct application.
Parameter Description Value cmd_id A four-byte identifier of the command that was found in the command text.
Note: The environment variable NDMAPICFG must be set to the pathname of the client configuration file. Refer to “Starting the CLI” on page 1for instructions on setting the environment variable. To use the ConnectDirectSession class, your application must include the cdunxsdk.h header file provided in the installation and must link with the ndmapi.a file. Following is a sample ConnectDirectSession class program: #include "cdunxsdk.h" #include #include
Method Description Parameter Return Values Connect Provides a connection to the Sterling Connect:Direct server. DisConnect Disconnects the current session. void CD_SUCCESS or CD_FAILURE SendCommand Sends a Sterling Connect:Direct command to the server for processing. Pointer to a command text buffer. CD_SUCCESS or CD_FAILURE ReceiveResponse Receives the response from a previously issued command, such as the select statistics command.
Method Description Parameter Return Values GetPreviousError Moves the error data pointer to the previous error in the list. void TRUE—If successful Moves the error data pointer to the first error in the list. void GetLastError Moves the error data pointer to the last error in the list. void TRUE—If successful, otherwise FALSE. GetMsgID Retrieves the message of the current error data block. void Return Value: Pointer to a message ID if data block is value.
// Methods for retrieving ReceiveResponse data... virtual const char *GetResponse(void) = 0; virtual int GetResponseLength(void) = 0; virtual bool MoreData(void) = 0; // Methods for retrieving SendCommand return data... virtual const char *GetCommandName(void) = 0; virtual long GetProcessNumber(void) = 0; virtual long GetProcessCount(void) = 0; // Methods to iterate over error collection ...
74 Sterling Connect:Direct for UNIX: User Guide
Chapter 5. Writing User Exits User Exit Programs The user exit API functions allow you to write custom programs to use with Sterling Connect:Direct. The user exit programs are used by Sterling Connect:Direct to invoke user-specific logic at strategic points within Sterling Connect:Direct execution. User exit programs must be C or C++ language programs and cannot be shell scripts.
C++ Function C Function Description exit_child_init() exit_child_init_c() Use this function as the first line in a user exit program to initialize communications between Sterling Connect:Direct and the user exit program. recv_exit_msg() recv_exit_msg_c() Used by both Sterling Connect:Direct and the user exit program to receive a message from the other Process. The receive exit messages wait for a response from the other Process.
Waiting for a Message Using recv_exit_msg() or recv_exit_msg_c() The recv_exit_msg() or recv_exit_msg_c() function waits until it receives a message from Sterling Connect:Direct. Control is suspended until a message is received or an error occurs.
The send_exit_file() or send_exit_file_c() function calls have the following return codes. Return codes for the function are defined in ndmapi.h. Header Header GOOD_RC The file descriptor was received successfully. ERROR_RC An error occurred and the file descriptor was not sent successfully. Possible causes include: Sterling Connect:Direct terminated, an invalid value used for the exit_flag or fd parameters, or the last message sent was not send_exit_msg.
Overview of User Exit Messages Sterling Connect:Direct sends and receives messages, using the send_exit_msg() and the recv_exit_msg() functions for a C++ program or the send_exit_msg_c() and the recv_exit_msg_c() functions for a C program. For the exact definition of the data sent in each message, see the files located in d_dir/ndm/include/ user_exit.h and d_dir/ndm/include/user_exit2.h. Note: The copy control block is defined in user_exit2.h.
v UNIX user name v A copy of the Sterling Connect:Direct copy control block v A copy of the Sterling Connect:Direct parsed sysopts structure (the copy control block contains the actual raw version from the process) FILE_OPEN_OUTPUT_REPLY_MSG The user exit program sends a reply message to the Sterling Connect:Direct FILE_OPEN_OUTPUT_MSG.
v VALIDATE_MSG v VALIDATE_REPLY_MSG CAUTION: If the security exit is used, Sterling Connect:Direct relies on it for user ID authentication. If the security exit is not implemented correctly, security can be compromised. GENERATE_MSG Sterling Connect:Direct sends a generate message to the user exit program at the start of a session to establish a security environment. The PNODE sends the GENERATE_MSG to the security exit to determine a user ID and security token to use for authentication on the SNODE.
VALIDATE_REPLY_MSG The user exit program sends a reply message to the Sterling Connect:Direct VALIDATE_MSG.
Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used.
incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.
This information is for planning purposes only. The information herein is subject to change before the products described become available. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. ITIL is a registered trademark, and a registered community trademark of the Office of Government Commerce, and is registered in the U.S. Patent and Trademark Office. UNIX is a registered trademark of The Open Group in the United States and other countries.
Index Special characters -e nn parameter, direct command 3 -h parameter, for direct 3 -n name parameter, direct command 3 -p nnnnn parameter, direct command 3 -r parameter, direct command 3 -s parameter direct command 2 -t nn parameter, direct command 2 -x parameter, direct command 3 -z parameter, direct 3 &symbolic name parameter, submit command 11 "Generic" Parameter Value 6 "List" Parameter Value 6 A Accessing Sterling Connect Direct Messages 46 API function calls 59 exit_child_init_c() function 76 exit
I informational responses, API 62 Initializing communications using user exit functions 76 L logfile parameter exit_child_init() function 76 M Managing Processes 37 maxdelay parameter 7 Message message ID format 46 Message file record format 47 Message File Content 46 Message file record format 47 Message files overview 46 Message text 47 Modifying a translation table 45 Modifying translation tables 44 Monitor Process Status in the TCQ 19 Monitoring Process status 22 Moving a CLI process foreground 4 msg
User Exit Stop Message (continued) STOP_MSG 82 Using the Stand-alone Batch Compression Utility 49 Using translation during file transfer operationg 45 Utilities translation table and the copy statement 45 V Validate configuration files 53 VALIDATE_MSG 81 VALIDATE_REPLY_MSG 82 view process command 4 W Wait queue 40 Waiting for a message using user exit functions 77 Wildcard facility 6 Writing Custom C Programs 61 Writing Custom C++ Programs 70 Writing Custom Programs 59 Index 89
90 Sterling Connect:Direct for UNIX: User Guide
Product Number: 5725-C99 Printed in USA
