Instruction/ maintenance manual of the product 4J IBM
Go to page of 98
St er ling C o nn e ct:Dire ct f o r UN IX Us e r G u id e Ve r s i o n 4 . 1 .
.
St er ling C o nn e ct:Dire ct f o r UN IX Us e r G u id e Ve r s i o n 4 . 1 .
Note Before using this information and the pr oduct 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 r eleases and modifications until otherwise indicated in new editions.
Contents Chapter 1. Controlling and Monitoring Processes .............. 1 Overview of the Command Line Interface .... 1 Starting the CLI ............ 1 Stopping the CLI ............ 1 CLI Commands ............ 1 CLI Job Control ............ 3 CLI History Commands .
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 fr om a native command line environment. Y ou can also use the Sterling Connect:Direct Br owser User Interface to perform some of these tasks.
Option Description V alue Sample Command Entry -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.
Option Description V alue Sample Command Entry -e nn Defines the error level above which the CLI automatically exits. If the returned err or code is greater than the err or level specified, the CLI automatically exits. Use this command within shell scripts.
enables you to edit the text of saved Processes, issue UNIX commands, and r esolve Process err ors 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 Pr ocess.
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.
v When typing commands, type the entire command name or type the first thr ee characters or abbreviate specific parameters. Refer to “Abbr eviations for Common Sterling Connect:Direct Commands” on page 5for a list of abbreviations. v Do not abbreviate Pr ocess statements and parameters.
Parameter Description V alues 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 recor d in the initialization parameters file.
Parameter Description V alues notify The user e-mail to receive Pr ocess 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 .
Parameter Description V alues snode Identifies the name of the secondary node. Setting this value overrides the snode value in the Process statement. The snode parameter is requir ed either on the submit command or Process statement. name | host name | nnn.
Parameter Description V alues snodeid Specifies security user IDs and security passwords on the SNODE. The snodeid subparameters can contain one or more alphanumeric characters. If Sterling Connect:Direct finds that a Pr ocess has no snodeid parameter or defines a snodeid parameter and the initialization parameter proxy .
Parameter Description V alues startt Identifies the date, day , and time to start the Process. Sterling Connect:Dir ect places the Process in the T imer queue in WS (W aiting for Start T ime) status. The date, day , and time are positional parameters.
Parameter Description V alues tracel Specifies the level of trace to perform for a Process. T racing by Process can be turned on in the submit command or as part of the Process definition.
Example - Submit a Process and T urn On T racing 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.
Parameter Description V alue 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.
Parameter Description V alue hold Moves the Process to the Hold or W ait queue. yes | no | call yes—Places the Process in the Hold queue in HO status until it is released by another change process command. no—Places the Process in the W ait queue in WC (W aiting for Connection) status; the Process executes as soon as resour ces are available.
Y ou select the Process to delete by Process name, Pr ocess 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 V alue pname Identify the Process to delete by Process name.
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 Pr ocesses from the Execution queue.
Parameter Description V alue submitter Locate the Pr ocesses 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.
Y ou can specify the force, immediate, quiesce, or step parameters with the stop command. Note: The force parameter is r equired when running Sterling Connect:Dir ect with the LU6.
Parameter Description V alue pname Locate the Process to view by Process name. The Process name is limited to 8 characters on Sterling Connect:Direct for Micr osoft W indows and Sterling Connect:Direct for z/OS. name | generic |( list ) name—Specifies the Process name, up to 8 alphanumeric characters.
Parameter Description V alue 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. E X|H C|H E|H I|H O|H R|H S|P E | WC | WR | WS | (list) EX (Execution)—Specifies to select Processes from the Execution queue.
Parameter Description V alue submitter Locate the Processes to view by the node specification (the Sterling Connect:Direct node name) and user ID of the Process owner .
Parameter Description V alue queue Specifies the Pr ocesses to be selected by the specified queue names. The default is all . all | exec | hold | wait | timer all—Selects Processes fr om all queues. this is the default. exec—Selects Processes fr om the Execution queue.
Parameter Description V alue 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. E X|H C|H E|H I|H O|H R|H S|P E |W C|W R|W S|( list ) EX (Execution)—Specifies to select Processes from the Execution queue.
Parameter Description V alue submitter Locate the Processes to select by the node specification (the Sterling Connect:Direct node name) and user ID of the Process owner .
Determining the Outcome of a Process The select statistics command is used to examine Process statistics fr om the Sterling Connect:Direct statistics file. The type of information in the statistics r eport includes copy status and execution events. The search criteria pr ovide flexibility in selecting information you want to display .
Parameter Description V alue pname Locate the statistics to select by Process name. The Process name is limited to 8 characters on Sterling Connect:Direct for Microsoft W indows and Sterling Connect:Direct for z/OS. name | generic |( list ) name—Specifies the Process name, up to 8 alphanumeric characters.
Parameter Description V alue 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. FMR V—Error occurr ed in function management.
Parameter Description V alue PSTR—Process started. QCEX—A Process moved fr om another queue to the EXEC queue. QCW A—A Process moved from another queue to the W AIT queue. QCTI—A Process moved fr om another queue to the TIMER queue. QCHO—A Process moved fr om another queue to the HOLD queue.
Parameter Description V alue 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.
Parameter Description V alue snode Locate the statistics file recor d 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.
Parameter Description V alue stopt Specifies that Sterling Connect:Direct sear ches for statistics recor ds up to and including the designated date, day , and time positional parameters.
Generating a Summary Report for a Process Y ou can use the select statistics command to generate a summary report for a Process. The following command generates summary statistics for Pr ocess number 9: sel stat pnumber=9 detail=no startt=(08/10/2008); The report consists of all r ecords fr om August 10, 2008.
Parameter Description V alue cmgr T o 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—T erminates the trace. 1—Is the basic level that provides function entry and function exit.
Parameter Description V alue pmgr T o 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—T erminates the trace. 1—Is the basic level that provides function entry and function exit.
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 Pr ocess ID.
Chapter 2. Process Queuing Overview of the T ransmission Control Queue The TCQ controls Pr ocess execution as Sterling Connect:Direct operates. After you submit a Process, it is stor ed in the TCQ. The TCQ consists of four queues: Execution, W ait, T imer , and Hold.
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.
The Execution Queue Processes ar e placed in the Execution queue after Sterling Connect:Direct connects to the remote node. Pr ocesses normally come from the W ait queue, but also can be placed in the Execution queue by a submit command with maxdelay=0 specified.
After a Process successfully completes, it is automatically deleted fr om the Execution queue. A flush process command with hold=yes moves a Process fr om the Execution queue and places it in the Hold queue. When a session is interrupted, the Pr ocess moves from the Execution queue to the T imer queue if retry values ar e specified.
The T imer Queue Processes ar e placed in the T imer queue by a submit command with the startt parameter specified. Processes in the W ait for Start T ime (WS) status are waiting for the start time to arrive before moving to the W ait queue.
Processes ar e placed in the Hold queue by a submit command with retain=initial, retain=yes, or hold=yes parameters specified. Pr ocesses submitted with hold=call also are placed in the Hold queue. Pr ocesses are moved fr om the T imer queue to the Hold queue by a change process command with hold=yes specified.
Chapter 3. Sterling Connect:Direct Utilities Introduction to T ranslation T ables Sterling Connect:Direct translates data fr om one character set code to a differ ent character set code, such as from ASCII to EBCDIC, based on a character translation table in the d_dir /ndm/xlate directory .
Compiling a T ranslation T able Using the ndmxlt Utility Before you begin Y ou can create or modify a translation table tailored to your r equirements with the ndmxlt utility program.
3. Add the following lines to the bottom of the table. It should look like the table in “Creating a T ranslation T able” 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.
T o 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.
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 recor d. Each recor d can be up to 4K bytes long.
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.
Using the Standalone Batch Compression Utility Before you begin T o 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 V alues -m Specify which mode to use: precompr ess or decompress.
Parameter Description V alues -p Use this option to specify codepages for file conversion. Default is no codepage translation. This parameter is mutually exclusive with -xlate. source codepage, destination codepage -d Specify the datatype of the file.
Parameter Description V alues -a Use this option to replace zero-length recor ds with a single, blank character . This parameter is valid only when you specify the following: “-d text” and “-m compress”. y|n y—yes n—no The default is y . Specify n if the data is copied to an i5OS or mainframe node.
cdsacomp -m decompress -d text -i compressed.file -o dest.file -x /home/cd/ndm/xlate/def_recv.xlt Examples—csdacomp Command Help Requesting a summary of cdsacomp command parameters and help options:.
V alidate 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.
v Sterling Connect:Direct Secur e Plus for UNIX v Sterling Connect:Direct for SWIFTNet for UNIX During the Sterling Connect:Direct installation, cdcustrpt is installed in the <installation> /etc/ directory .
########################################################################### ####### Connect:Direct for UNIX 4.0.00 configuration report ####### ########################################################.
The following example shows an excerpt from a sample r eport: ===== Begin: Secure+ parameters ===== ========================================= All secure+ nodes: ************************************************************** * Secure+ Command Line Interface * * Connect:Direct for UNIX v4.
Log.MaxVersions="5" [connection.info] # Connection information for Connect:Direct’s API port. (Used when forwarding files to the back office.
58 Sterling Connect:Direct for UNIX: User Guide.
Chapter 4. Writing Custom Programs Introduction to W riting 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:Dir ect.
Platform C++ Compile Command 64-bit /opt/SUNWspro/bin/CC -xar ch=generic64 -DBSD_COMP -I../include -o sdksample sdksample.C ../lib/ndmapi64.a -L/usr/ucblib/sparcv9 -L/usr/lib/spar cv9 -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.
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.
C++ Function C Function Description ndmapi_sendcmd() ndmapi_sendcmd_c() Sends commands to Sterling Connect:Direct. Y ou must provide the command text. The resp_mor eflag is a pointer to the flag indicating that more r esponses are pending for the executed command.
from the commands. Contr ol returns to the application when the connection is established and Sterling Connect:Direct is r eady 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 r esponses that are associated with a previous command sent fr om the application.
Parameter Description V alue DDS1—Destination disposition 1 DDS2—Destination disposition 2 DDS3—Destination disposition 3 DESC—Sterling Connect:Direct administrator description DFIL—Destinat.
Parameter Description V alue PNOD—PNODE PNUM—Process number PPMN—PDS member name PR TY—Priority QUEU—Queue RECC—Record category RECI—Record ID RET A—Retain Process RMTP—Remote IP add.
Parameter Description V alue ST A T—Process status SNOD—SNODE SNVL—Source number of volumes SOPT—SYSOPTS recor d SRCR—Records r ead SRUX—RUs sent STIM—Schedule time STOP—Stop time of t.
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 V alue cmd_id A four -byte identifier of the command that was found in the command text. Following are the four -byte identifiers: /**************Command IDs*******************/ .
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. T o use the ConnectDirectSession class, your application must include the cdunxsdk.
Method Description Parameter Return V alues Connect Provides a connection to the Sterling Connect:Direct server . Connect() with a void parameter connects to the hostname and port specified in the client configuration file. void or a pointer to an IP address and port.
Method Description Parameter Return V alues GetPreviousErr or Moves the error data pointer to the previous err or in the list. void TRUE—If successful F ALSE—If no previous err or exists. GetFirstError Moves the error data pointer to the first error in the list.
// 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.
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 pr ograms are used by Sterling Connect:Dir ect to invoke user-specific logic at strategic points within Sterling Connect:Dir ect execution.
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 pr ogram.
W aiting for a Message Using recv_exit_msg() or recv_exit_msg_c() The recv_exit_msg() or r ecv_exit_msg_c() function waits until it receives a message from Sterling Connect:Dir ect. Control is suspended until a message is r eceived 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 occurr ed and the file descriptor was not sent successfully .
Overview of User Exit Messages Sterling Connect:Direct sends and r eceives 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 fo raCp r ogram.
v UNIX user name v A copy of the Sterling Connect:Direct copy contr ol block v A copy of the Sterling Connect:Direct parsed sysopts str ucture (the copy control block contains the actual raw version from the pr ocess) FILE_OPEN_OUTPUT_REPL Y_MSG The user exit program sends a r eply message to the Sterling Connect:Direct FILE_OPEN_OUTPUT_MSG.
v V ALIDA TE_MSG v V ALIDA TE_REPL Y_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.
V ALIDA TE_REPL Y_MSG The user exit program sends a r eply message to the Sterling Connect:Direct V ALIDA TE_MSG. The V ALIDA TE_REPL Y_MSG contains: v Status value of zero for success or non zer o fo.
Notices This information was developed for products and services of fered in the U.S.A. IBM may not offer the pr oducts, services, or features discussed in this document in other countries. Consult your local IBM repr esentative for information on the products and services curr ently available in your area.
incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the pr ogram(s) described in this publication at any time without notice. Any refer ences in this information to non-IBM W eb sites are provided for convenience only and do not in any manner serve as an endorsement of those W eb sites.
This information is for planning purposes only . The information herein is subject to change before the pr oducts described become available. This information contains examples of data and reports used in daily business operations.
Microsoft, W indows, W indows NT , and the W indows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. ITIL is a registered trademark, and a r egistered community trademark of the Of fice of Government Commerce, and is r egistered in the U.
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 pa.
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 messag.
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 statemen.
90 Sterling Connect:Direct for UNIX: User Guide.
.
Product Number: 5725-C99 Printed in USA.
An important point after buying a device IBM 4J (or even before the purchase) is to read its user manual. We should do this for several simple reasons:
If you have not bought IBM 4J yet, this is a good time to familiarize yourself with the basic data on the product. First of all view first pages of the manual, you can find above. You should find there the most important technical data IBM 4J - thus you can check whether the hardware meets your expectations. When delving into next pages of the user manual, IBM 4J you will learn all the available features of the product, as well as information on its operation. The information that you get IBM 4J will certainly help you make a decision on the purchase.
If you already are a holder of IBM 4J, but have not read the manual yet, you should do it for the reasons described above. You will learn then if you properly used the available features, and whether you have not made any mistakes, which can shorten the lifetime IBM 4J.
However, one of the most important roles played by the user manual is to help in solving problems with IBM 4J. Almost always you will find there Troubleshooting, which are the most frequently occurring failures and malfunctions of the device IBM 4J along with tips on how to solve them. Even if you fail to solve the problem, the manual will show you a further procedure – contact to the customer service center or the nearest service center
