IBM Connect:Direct for UNIX Process Parameters
- ckpt = no | n | nK | nM | nG
specifies the byte interval for checkpoint support, which allows restart of interrupted transmissions at the last valid checkpoint point and therefore reduces the time to retransmit the file. If the ckpt parameter and value are not specified, the default is the value specified by the ckpt.interval parameter in the Initialization Parameters file. Specify this parameter between the from and to parameters.
The following table shows the maximum number of digits for each option.
Option Byte Interval no no checkpointing nnnnnnnnnn number of bytes nnnnnnnK number of kilobytes nnnnM specifies a number of megabytes nG specifies a number of gigabytes - class = n
determines the node-to-node session on which a Process can execute. A Process may execute on the class specified or any higher session class. The default class is specified as the sess.default parameter in the Initialization Parameters file. The class default is 1.
- compress [ [primechar = x’xx’ | x’20’ | c’c’] | [extended [=(CMPrlevel=1|2|3|4|5|6|7|8|9 WINdowsize=9|10|11|12|13|14|15 MEMlevel=1|2|3|4|5|6|7|8|9)] ]
-
specifies that the data is to be compressed, which reduces the amount of data transmitted as the file is copied from one node to another. The file will be automatically decompressed at the destination. The default subparameter for the compress parameter is primechar=x’20’. Use compress for text data or single-character repetitive data. Use compress extended for all other types of data. Specify this parameter between the from and to parameters.
Note: If the SNODE is B2B Integrator, only COMRESS EXT is supported.primechar specifies the primary compression character. The default value for primechar is x’20’.
IBM® Connect:Direct® reduces the amount of data transmitted based on the following rules:
- Repetitive occurrences (ranging from 2-63) of the primary compression character will be compressed to one byte.
- Repetitive occurrences (ranging from 3-63) of any other character will be compressed to two bytes.
extended is used to search for repetitive strings of characters in data and compress them to codes that are transmitted and converted back to the original string during decompression. It is advantageous to specify this parameter when line transmission speeds are limited and data is repetitive. Use CMPrlevel, WINdowsize, and MEMlevel to refine the extended compression.
CMPrlevel is the compression level used. Level 1 is the fastest but offers the least degree of compression. Level 9 provides the greatest degree of compression but the slowest rate of compression. The default is 1 unless overridden in the initialization parameters.
WINdowsize specifies the size of the compression window or history buffer. The greater the window size is, the greater the degree of compression but at the cost of a greater amount of virtual memory that is used. The default is 13. The following table indicates the approximate amount of memory used for each window size.
Window Size Memory Used 9 2K 10 4K 11 8K 12 16K 13 32K 14 64K 15 128K MEMlevel specifies how much virtual memory should be allocated to maintain the internal compression state. Memory level 1 uses the least amount of memory, but slows processing and reduces the degree of compression. Memory level 9 provides the fastest speed but uses the most memory. The default is 4. The following table shows approximate memory usage for each memory level setting.
Memory Level Memory Usage 1 1K 2 2K 3 4K 4 8K 5 16K 6 32K 7 64K 8 128K 9 256K - condition
The condition parameter specifies the type of comparison that will be performed. This condition checking can be based on such comparisons as equal to, greater than, or less than. The valid conditions are as follows:
- == | = | eq specifies that the return code must be equal to the value nn for the condition to be satisfied.
- <> | != | ne specifies that the return code must not equal the value nn for the condition to be satisfied.
- >= | => | ge specifies that the return code must be greater than or equal to the value nn for the condition to be satisfied.
- > | gt specifies that the return code must be greater than the value nn for the condition to be satisfied.
- <= | =< | le specifies that the return code must be less than or equal to the value nn for the condition to be satisfied.
- < | lt specifies that the return code must be less than the value nn for the condition to be satisfied.
- copy
identifies the copy statement.
- crc =on | off
determines if CRC checking is activated for a process. To define this parameter, the user must be given the authority to perform CRC checking in the user authority. You can globally turn on CRC checking using the initialization parameter. CRC checking can only be performed for TCP/IP processes and cannot be used by Processes using Connect:Direct Secure Plus or SNA. If CRC checking is enabled for a Process on a Connect:Direct Secure Plus enabled node or on a computer with SNA enabled, CRC checking is ignored.
When CRC checking is performed, the copy termination statistics record contains a message indicating that CRC was performed for a Process.
- disp = [(] new | mod | rpl [)]
- defines the state that the target file should be in when it is opened. The disp parameter also determines how the file should be opened, either new, mod, or rpl.
- new indicates the file must not already exist.
- mod indicates that if the file already exists, data will be appended to the end of the file. If the file does not exist, then mod behaves as if new is specified.
- rpl indicates that copy to will act as if disp=new was specified if the file does not already exist. If the file exists, then it will be overwritten. The default is rpl.
- dsn = dsn[(member)]
specifies the name of the data set containing the job to be submitted. If the file is a PDS, the member containing the job must be specified. The data set containing the job must already exist on the node where the job will be submitted. This parameter is required.
- eif
is required for specifying the end of the if then or if then else block of statements. No parameters exist.
- else
designates a block of IBM Connect:Direct statements that execute when the if then condition is not satisfied. No parameters exist.
- exit
is used to bypass all remaining steps within a Process. No parameters exist.
- file = filename
specifies the name of the file that contains the Process. The file name may include a pathname indicating the location of the Process. There is no practical limit on the character length of the file parameter. This parameter is required.
Note: A pathname recognized in cli is relative to the current working directory. An absolute path (starting from root "/") will always work.Enclose the file name in double quotation marks when using a reserved word (statement name or keyword) for the file name.
- file = filename | dsn = filename | file = "unix command [;unix command [;unix command...]]"
The file or dsn parameter specifies the optional path name and required file name. The file name can be enclosed in double quotation marks.
If
sysopts="pipe=yes"
, the file parameter specifies a UNIX command to execute. The command can be a command, program, or shell script including any options and arguments.When specifying file = filename, enclose the file name in double quotation marks when using a reserved word (statement name or keyword) for the file name.
Connect:Direct for UNIX supports the string (*) and character (?) wildcards, allowing you to copy multiple files from a source directory to a target directory with a single copy command.
You can use a Connect:Direct for UNIX node to perform a wildcard copy send to any other IBM Connect:Direct platform. With a IBM Connect:Direct UNIX node, you can receive a wildcard copy only from a Connect:Direct for Microsoft Windows node or from another Connect:Direct for UNIX node.
- from
specifies the source file characteristics. This parameter is required.
- goto
moves to a specific step within a Process. See the following Field Descriptions section for details.
- hold = yes | no | call
specifies how the Process is handled in the Hold queue.
yes specifies that the Process is held in the Hold queue in HI status until it is released by a change process command. When hold=yes and a startt value is specified, the hold parameter takes precedence. A Process submitted with hold=yes is placed in the Hold queue even if a start time is specified.Note: When a Process is submitted with retain=yes and hold=no or hold=call, the hold parameter is ignored.no specifies that the Process is not held in the Hold queue. It is executed as soon as resources are available. The default is no.
Setting hold to no value, such as hold or hold=, does not produce an error. It is another way of placing the Process in the Hold queue similar to setting Hold=yes.
call specifies that the Process is held (no prompt returns) until the remote node (snode) connects to the local node (pnode). At that time, the Process is released for execution. The Process is also released when another Process on the local node connects to the snode.
- if then
specifies that a block of IBM Connect:Direct statements execute based on the completion code of a Process step. An eif statement must be used in conjunction with an IF THEN statement.
- Label
IBM Connect:Direct statements are identified by user-defined labels. A label is any character or character string beginning in column one. The label consists of a 1-256 character alphanumeric string.
Statement names and keywords are reserved and cannot be used as labels.
You can use the label to identify the Process in any messages or statistics relating to this Process
Although the IBM Connect:Direct UNIX label may be up to 256 characters long, labels for many of the IBM Connect:Direct platforms cannot exceed eight characters.
A label is required for the Process statement to define a Process name. The Process name can be used as the pname parameter value on the change process, delete process, flush process, select process, and select statistics commands for the name of the target Process. The Process statement must be on the same line as the label.
A label is not required on any other IBM Connect:Direct UNIX statement.
- newname = new process name
specifies the new name to be given to the Process. This value overrides the label on the process statement. There is no practical limit on the character length of the newname parameter.
- nn
This parameter specifies the numeric value to be used for return code checking. If specified as x’nn’, it is a hexadecimal value. Any other specification indicates it is decimal. Standard return codes are as follows:
- 0 indicates successful completion.
- 4 indicates warning.
- 8 indicates error.
- 16 indicates catastrophic error.
- notify = username@hostname or user@localhost
specifies the user name to receive Process completion messages. This parameter uses the rmail utility available in the UNIX System V mail facility to deliver the completion messages.
- pacct = “pnode accounting data”
specifies accounting data for the pnode. The maximum length of the string is 256 characters. The string must be enclosed in double quotation marks.
- pend
The pend statement is optional and marks the end of an IBM Connect:Direct UNIX Process. There are no parameters associated with the pend statement.
- pgm = program-name
specifies the name of the program to be attached as the subtask. The program runs on the node specified and has access to the DD cards allocated on that node only.
- plexclass=remote_plexclass
specifies the 1–8 character name of a valid plexclass on the remote server. This parameter gives you control over which IBM Connect:Direct/Plex Server is selected by the IBM Connect:Direct/Plex Manager to execute a Process. For example, you can specify plexclass=tape in a Process to direct a Process to a IBM Connect:Direct/Plex Server that has a tape drive.
- pnode
When specified on the copy from parameter, the file to be copied resides on the primary node. When specified on the copy to parameter, the file is sent to the primary node. Pnode is the default for the from parameter.
On a run job or run task statement, specifies that the job executes on the PNODE.
- pnodeid = (id ,pswd)
specifies security information for the Process on the pnode. Each pnodeid parameter value can be 1-64 alphanumeric characters long.
id specifies the user ID to be used as a security ID on the pnode.
pswd specifies a user password on the pnode.
If pswd is specified, id also must be specified. These values must be specified in the order of id and pswd.
- prty = nn
specifies the priority of the Process on the Transmission Control Queue (TCQ). The prty parameter is used only for Process selection. A Process with a higher priority is selected for execution before a Process with a lower priority. The value specified for the prty parameter does not affect the priority during transmission. Values range from 1-15. The highest priority is 15. If prty is not specified, the default is 10.
- retain = yes | no | initial
specifies whether the Process is retained on the TCQ in the Hold queue for re-execution after execution has completed.
yes specifies that the Process is retained on the Hold queue in HR status after execution. The Process must then be released manually through the change process command to cause it to be executed, or explicitly deleted through the delete process command. When a Process is submitted with retain=yes and hold=no or hold=call, the hold parameter is ignored.
no specifies that the Process is not retained. The default is no.
initial specifies that the Process is retained on the Hold queue in HR status and automatically executed each time the Process Manager initializes. The startt parameter should not be specified when retain=initial is specified. This causes the SUBMIT command to fail.
- run job
identifies the run job statement.
- run task
identifies the run task statement.
- sacct = “snode accounting data”
specifies accounting data for the snode. The maximum length of the string is 256 characters. The string must be enclosed in double quotation marks.
The sacct parameter overrides any accounting data specified on the process statement of the submitted Process.
- SECURE=(OFF)
or
SECURE=(<protocol>[, [<cipher_suite> | (cipher_suite_list)] ] [,ENC[RYPT.DATA]=Y|N] )
or
SECURE=(ENC[RYPT.DATA]=Y|N) -
turns on security for a specific session by allowing you to select a protocol (SSL, TLS, TLS1.1, or TLS1.2) and one or more ciphers when non-secure sessions are the default or turns off security when secure sessions are the default. In addition, you can specify the type of encryption you want performed. Secure+ must be configured to allow overrides or this parameter will generate an error on process submission.Note: See the table below for details on protocol and cipher_suite specifications.
Parameter Definition ,ENCRYPT.DATA=Y|N or
ENC=Y|N
Depending on the option chosen, encrypts both the control block information contained in Function Management Headers (FMHs) and the files being transferred (ENC=Y) or encrypts only the FMHs (ENC=N). - ENCRYPT.DATA must be the last (or only) value specified on the SECURE= parameter.
- Both sides of the connection must support ENCRYPT.DATA= for SSL/TLS.
OFF Attempts to start the session as a non-secure session. The session will be successfully established if Secure+ on the snode has been configured to allow overrides or is configured for non-secure sessions. SSL | TLS | TLS1.1 | TLS1.2 Attempts to start the session as a secure session using the specified protocol. The session will be successfully established if Secure+ on the snode has been configured to allow overrides or is configured for the specified protocol.
Cipher Suite Specifies the one cipher suite for IBM Connect:Direct to use when executing the Process overriding the cipher suite defined in the Secure+ parameters file, for example, SSL_RSA_WITH_3DES_EDE_CBC_SHA. (Cipher suite list) Specifies a list of cipher suites for IBM Connect:Direct to use when executing the Process overriding the cipher suite defined in the Secure+ parameters file. The cipher list must be enclosed in parentheses and each cipher suite separated by a comma, for example, (TLS_RSA_AES_128_SHA,TLS_RSA_AES_256_SHA,
TLS_RSA_WITH_DES_CBC_SHA) - snode
When specified with the copy from parameter, the file to be copied resides on the secondary node. When specified with the copy to parameter, the file is sent to the secondary node. Snode is the default for the to parameter.
On a run job or run task statement, specifies that the job executes on the PNODE.
- snode = [nodename] | [(hostname | nnn.nnn.nnn.nnn);(port number | portname)]
is a 1-256 alphanumeric character string that specifies the node name of the secondary node. The snode default value is the value specified in the process statement. It is required either on the submit command or process statement.
nodename is the node name of the adjacent IBM Connect:Direct node. The secondary node name corresponds to an entry in the network map file.
hostname is the name of the host machine where the remote IBM Connect:Direct is running. This is applicable only for TCP/IP.
nnn.nnn.nnn.nnn is the IP address of the remote IBM Connect:Direct node. Each nnn is a decimal number from 0-255, inclusive. This is applicable only for TCP/IP.
portnumber | portname identifies the communications port for the IBM Connect:Direct software. The portnumber is a decimal number from 1024-65535. The default is 1364. This is applicable only for TCP/IP.
- snodeid = (id [,pswd[,newpswd]])
specifies security user IDs and security passwords for the Process on the SNODE. Each snodeid parameter value can be 1-64 alphanumeric characters.
id specifies the user ID to be used as a security ID on the snode.
pswd specifies the user password on the snode.
newpswd specifies the new password value. The user password is changed to the new value on the snode if the user ID and old password are correct. The newpswd parameter is not valid if the snode is a IBM Connect:Direct UNIX node.
If pswd is specified, id also must be specified. If newpswd is specified, pswd also must be specified. These values must be specified in the order of id, pswd, and newpswd.
- startt = ([date | day] [,hh:mm:ss [am | pm]])
specifies that the Process is executed at a specified date and/or time. The Process is placed in the Timer queue in WS status. The date, day, and time values are positional subparameters. If date or day is not specified, a comma must precede time.
The startt parameter should not be specified when retain=initial is specified. This causes the submit command to fail.
date specifies that the Process will execute on a specific date. You can specify the date subparameter in the format mm/dd/yyyy or mm-dd-yyyy, where:
- mm indicates month
- dd indicates day
- yyyy indicates year
If only date is specified, time defaults to 00:00. The current date is the default.
day specifies the day of the week a Process is released for execution. Values are today, tomorrow, monday, tuesday, wednesday, thursday, friday, saturday, and sunday.
If only day is specified, time defaults to 00:00:00. For example, if a Process is submitted on Monday, with monday as the only startt parameter, the Process does not run until the following Monday when the time reaches 00:00:00.
hh:mm:ss [am | pm] specifies the hour (hh), minute (mm), and second (ss) the Process should start. You can specify hour in either 12- or 24-hour format. If you use 12-hour format, you must specify am or pm. A space is required before am or pm. The default is 24-hour format. The default value is 00:00:00.
When both hold=yes and a startt value are specified, the hold specification takes precedence. Therefore, a Process submitted with hold=yes is placed on the Hold queue even if a start time is specified
- submit
identifies the submit statement.
- subnode = pnode | snode
specifies the node on which the Process will be submitted. The Process must reside on the node on which it is being submitted.
pnode specifies that the Process is submitted on the node that has Process control. The default value is pnode.
snode specifies that the Process is submitted on the node participating in, but not controlling, Process execution.
- &symbolic name1 = variable string 1
&symbolic name2 = variable string 2
.
.
.
&symbolic namen = variable string n specifies the value for a symbolic parameter in the Process. This default can be overridden when submitting the Process. The value is substituted within the Process when the symbolic parameter is encountered. Enclose the symbolic parameter value in double quotation marks if it is a keyword or contains special characters. A symbolic name cannot exceed 32 characters.
The symbolic parameter can be set to a single ampersand symbolic parameter that was resolved during the first Process submission. Do not use identical symbolic names.
If a symbolic value is a double quoted string and it is desired to preserve the double quotes when the symbol is resolved in the process, enclose the double quoted string in single quotes. For example:
&filename = '"file name with spaces"'
- sysopts=":datatype=text | binary:"
":xlate=no | yes:"
":xlate.tbl=<pathname/filename>:"
":strip.blanks=yes | no:"
":permiss=nnn:"
":pipe=yes | no:"
":codepage=(source codepage, destination codepage):"
" :precomp=yes | no:"
":recdl=x<hex value of record delimiter>:" specifies system-specific parameters on the copy statement. The subparameters are specified in the same format as fields within a IBM Connect:Direct UNIX configuration file. They are a series of field names and values (fldn=valn), each of which is delimited by a colon. Enclose the string of subparameters in double quotes; for example:
":fld1=val1:fld2=val2:...:fldn=valn:"
datatype specifies the type of data contained within the file: text, binary, or vb.
text indicates it is a text file. The default is text. The following shows the default source file attributes assigned for UNIX text files, which are to be used if necessary by the remote IBM Connect:Direct node:
- dsorg=ps
- recfm=vb
- lrecl=23036
- blksize=23040
binary indicates the file contains binary data. The following shows the default source file attributes assigned for UNIX binary files, which are to be used if necessary by the remote IBM Connect:Direct node:- dsorg=ps
- recfm=u
- lrecl=0
- blksize=23040
vb indicates the file is in variable block format. Variable block format is structured as follows:
BDW | RDW | Data . . . | BDW | RDW | Data . . .
- BDW=block descriptor word containing 2 bytes for the length of the block (including 4 bytes of the BDW) and 2 bytes of zeros
- RDW=record descriptor word containing 2 bytes for the length of the block (including 4 bytes of the RDW) and 2 bytes of zeros
- Data=record of user data equal in length to the RDW minus the 4 bytes of the RDW (for example, an RDW of 76 bytes is followed by a record of 72 bytes)
Note: The vb feature does not support ASCII/EBCDIC translation. If you specify ":datatype=vb:", specify ":xlate=no:". The copy will fail if you specify ":xlate=yes:".xlate = no | yes indicates whether character translation should be performed using the default or user-supplied translation table. Typically, this translation is between ASCII and EBCDIC.- no specifies the translation is not performed. no is the default for binary files.
- yes specifies the translation is performed. yes is the default for text files.
xlate.tbl =<pathname/filename> specifies that a translation table is to be used that is different from the default table used by the IBM Connect:Direct software.
strip.blanks determines whether trailing blank characters are removed from a line of text before it is written to the UNIX text file.- yes specifies to remove trailing blank characters. This is the default.
- no specifies trailing blank characters are not removed.
permiss=nnn specifies the UNIX file permissions for a file being created by the copy operation. The permiss subparameter is ignored if it is specified for a file that already exists.
nnn is a 3-digit octal number that defines privileges for users. Each type of user (owner, group, and others, respectively) can be assigned read, write, and execute privileges.
The following table shows valid octal numbers and associated permissions for each n based on the binary numbering system:
Octal Binary Permissions 0 000 No permissions 1 001 Execute permission 2 010 Write permission 3 011 Write and execute permissions 4 100 Read permissions 5 101 Read and execute permissions 6 110 Read and write permissions 7 111 Read, write, and execute permissions For example,
permiss=634
indicates that the owner has read and write permissions, the group has write and execute permissions, and others have read permissions.pipe = yes | no specifies whether the pipe I/O function is activated. The pipe I/O function allows commands, programs, or shell scripts including any options and arguments to be copied to the destination file or from the source file.- yes specifies the pipe I/O function is activated.
- no specifies the pipe I/O function is not activated.
Note: Checkpoint/restart is not supported for the pipe I/O function.codepage=(source codepage, destination codepage)=yes | no specifies whether IBM Connect:Direct will automatically decompress a file that was ressed with the cdsacomp utility. See the IBM Sterling Connect:Direct for UNIX User’s Guide for more information on the cdsacomp utility.- Yes indicates that the from data set is ressed and tells IBM Connect:Direct to decompress the file as part of the Process.
- No tells IBM Connect:Direct that the from file is not compressed, or to send the compressed file in compressed format. ressed files copied with this value can be decompressed offline on another Connect:Direct for UNIX or Connect:Direct for UNIX system using the cdsacomp utility.
If sysopts are not coded or if
sysopts=":=no:"
, a ressed file is sent in compressed format and the receiver must run cdsacomp with "-mode decompress". If the from file is not compressed, regular or extended compression may be used in the Copy step. Do not use regular or extended compression in the Copy step if the from file is compressed.codepage=(source codepage, destination codepage)
determines which codepage is used to translate a file.
Note: If you do not identify two parameters (source codepage, destination codepage) in the from statement or in the to statement, the codepage listed as the source is converted to UTF-8, sent, and then converted to the codepage identified in the to statement at the destination location. When this occurs, the file can be translated incorrectly.Three methods can be used to translate files:
- sysopts=":codepage=(source codepage, destination
codepage):"
This definition can be used either in the from or to statement and identifies the codepages used for translating a file either before it is transferred (from) or after it is received at the destination location (to).
- from sysopts=":codepage=source codepage:" to sysopts=":codepage=destination
codepage:"
This definition translates the file using the source codepage defined in the from statement to UTF-8 format, transfers the file, and then translates it at the destination from UTF-8 to the codepage defined in the to statement. See the note above.
- from sysopts=":codepage=(source codepage, transitional
codepage):" to sysopts=":codepage=(transitional
codepage, destination codepage):"
This definition translates the file using the source codepage defined in the from statement to the transitional codepage, transfers the file, and then translates it at the destination location from the transitional codepage to the destination codepage defined in the to statement. If UTF-8 is used as the transitional codepage, then this translation method performs the same as the second translation method described above.
Codepage translation supports the translation of text or binary files. When translating text files, codepage translates one line at a time. The trailing line feed character is removed from the text line. If the strip.blanks parameter is set to yes, trailing blanks are removed from the file and a line feed is appended to the line of text.
- :precomp=yes | no:
-
Specifies that Connect:Direct will automatically decompress a file that was precompressed with the cdsacomp utility. See the Connect:Direct for UNIX User’s Guide for more information on the
cdsacomp
utility.Yes indicates that the from data set is precompressed and tells Connect:Direct to decompress the file as part of the Process.
No indicates in Connect:Direct that the from file is not precompressed, or to send the precompressed file in compressed format. Precompressed files copied with this value can be decompressed offline on another Connect:Direct for UNIX or Connect:Direct for z/OS system using the
cdsacomp
utility.If sysopts are not coded or if
sysopts=":precomp=no:"
, a precompressed file is sent in compressed format and the receiver must run cdsacomp with"–mode decompress"
. - recdl=x<hex value of record delimiter>
-
provides a way to specify a non-standard record delimiter for source and destination text files. For example, if the source file is EBCDIC and uses the EBCDIC NL (new line character) as the record delimiter, the source file sysopts would include
:RECDL=x15:
. - sysopts = “unix command [;unix command [;unix command...]]”
specifies a UNIX command to execute under a B shell. The command can be a command, program, or shell script including any options and arguments. Specify the command as if it were being issued at a UNIX terminal. This parameter is required.
The run job statement does not wait until the UNIX command is completed to complete execution. Once started, the UNIX command or commands in a run job statement will be permitted to continue execution. Connect:Direct for UNIX does not have control over the UNIX commands.
The run task statement waits until the UNIX command has completed execution. The UNIX command or commands executed in a run task step can be terminated by a flush process force or a stop force or stop immediate command.
- then
specifies subsequent processing based on the other specified parameters.
- to
specifies the destination file characteristics. This parameter is required