Connect:Direct for Microsoft Windows Process Parameters

class = n

determines the node-to-node session on which a Process executes. A Process can execute in the class specified or any higher session class up to the maximum allowed for an snode (sess.pnode.max). The default class is specified as the sess.default parameter in the initialization parameters. The class default in the initialization parameters is 1.

ckpt=no | nnnnnnnnk | nnnnnnnnm

specifies the byte interval for checkpoint support. Checkpoint support allows restart of interrupted transmissions at the last valid checkpoint, reducing the time necessary 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.

no specifies no checkpointing.

nnnnnnnnk specifies the number of kilobytes.

nnnnnnnnm specifies the number of megabytes.

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.

Note: Not all combinations of source and destination codepages may be supported by the underlying platform. If the COPY step fails with an MBCS001E error, try the third method below using UTF-8 or UTF-16 as the transitional codepage.

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 preceding note.
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.

compress [[primechar = x’xx’ | x’20’ | c’c’ ]| extended]

specifies that the data is compressed to reduce the amount of data transmitted as the file is copied from one node to another. The file is automatically decompressed at the destination. Use prime-character compression for text data or single-character repetitive data. Use compress extended for all other types of data.

Note: If the SNODE is B2B Integrator, only COMRESS EXT is supported.

primechar specifies the primary compression character. This character is specified as a hexadecimal constant (x’xx’) or a character constant (c’c’). The default value for primechar is x’20’.

Connect:Direct® for Microsoft Windows reduces the amount of data transmitted according to the following rules:

Repetitive occurrences (ranging from 2-63) of the primary compression character are compressed to one byte.
Repetitive occurrences (ranging from 3-63) of any other character are compressed to two bytes.

extended searches for repetitive strings of characters in data and compresses them to codes that are transmitted and converted back to the original string during decompression. This method is advantageous when line transmission speeds are limited and data is repetitive.

condition

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.

disp = [(] new | mod | rpl | shr [)]

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.

shr indicates the file must already exist and will be overwritten.

dsn=Windows

specifies the job as either a Microsoft Windows program or command. This field 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.

execprty = nn

specifies the operating system priority to be assigned to the Process. The execprty keyword determines how Microsoft Windows schedules the Session Manager, which runs the Process, for execution relative to other tasks in the system. A Process with a higher priority receives more opportunities for execution from the operating system than a Process with a lower priority. Values range from 1-15. If execprty is not specified, the default is 7.

Scheduling Processes to run with a high priority may have an adverse effect on the execution of other applications in the system.

exit

is used to bypass all remaining steps within a Process. No parameters exist.

file=filename | dsn=filename

specifies the 1-256 character file name on the copy statement. This parameter is required for both the from and to parameters. A path specification and file server name are optional. If a remote file server name is specified as part of the file name, the remote server must be a Microsoft Windows version 3.51 or later system.

Connect:Direct for Microsoft Windows supports the string (*) and character (?) wildcards, allowing you to copy multiple files from a source directory to a target directory with a single copy statement.

Specify the UNC form of the filename if the file is not on a drive directly connected to the Microsoft Windows server where IBM Connect:Direct resides. The UNC name format is as follows:

\servername\share point name\filename

Replace the servername with the name of the Microsoft Windows server where data resides. The share point name represents the name under which the remote Microsoft Windows server shares the directory you want to access. The filename specifies the name of the file and includes any subdirectories, if appropriate.

If the file is on the Microsoft Windows server where IBM Connect:Direct is installed, you can specify the drive letter.

Enclose the file name in double quotation marks if you use a statement name, parameter name, or subparameter name for the file name.

file = filename

specifies the 1-256 character file name of the file containing the Process in the submit statement. The file parameter can include a pathname indicating the location of the Process. If the file parameter does not include a pathname indicating the location of the Process, the directory specified in the process.dir initialization parameter is searched.

If you specify the file parameter, it must be specified before any other parameter. If you do not specify the file parameter, the text of the Process must follow the submit command.

Enclose the file name in double quotation marks if you use a statement name, parameter name, or subparameter name for the file name.

This field is required.

from

specifies the parameters and subparameters that define the source file characteristics. This field is required.

goto

moves to a specific step within a Process. See the following Field Descriptions section for details.

hold = yes | no | call

specifies that a Process is held from executing until released.

yes indicates that the Process is held until it is explicitly released by a change process command. When both hold=yes and startt values are specified, the hold specification takes precedence. So, a Process submitted with hold=yes is placed in the Hold queue even if a start time is specified.

no indicates that the Process is not held and is executed as soon as resources are available. This is the default value.

call specifies that the Process is held until the snode connects to the pnode. At that time, the Process is released for execution. The Process is also released when another Process on the pnode connects to the snode.

When a Process is submitted with retain=yes and hold=no or hold=call, the hold parameter is ignored.

if then

specifies that IBM Connect:Direct executes a block of IBM Connect:Direct statements based on the completion code of a Process step. An eif statement must be used in conjunction with an if/then statement. See the following Field Descriptions section for details.

Label

IBM Connect:Direct statements are identified by user-defined 1-8 character alphanumeric labels. The label must begin in position one.

Statement names and keywords are reserved and cannot be used as labels.

Labels are required on the Process statement. The Process statement must be on the same line as the label.

In a conditional statement, the label parameter specifies the step to which the condition applies. This parameter is required in a conditional statement.

localacct = “pnode node 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.

newname = new process name

specifies the new name to be given to the Process. This value overrides the label on the process statement. The maximum length for the newname parameter is eight characters. The default is the label on the process statement.

nn

specifies the numeric value used for return code checking of the step named in the label. 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

specifies the user name to receive Process completion messages.

pend

The pend statement marks the end of the Connect:Direct for Microsoft Windows Process. No parameters are associated with the pend statement.

pgm=Windows

specifies the task as either a Microsoft Windows program or command. This field is required.

pnode | snode

On a copy statement, this parameter specifies whether the file is sent from the pnode or the snode. as shown on the following table:

Value	From Parameter	To Parameter
pnode	File to be copied is sent from the pnode. This is the default for the from parameter	File to be copied is sent from the snode
snode	File to be copied is sent from the snode	File to be copied is sent to the snode. This is the default for the to parameter/

For a run task or run job statement, this value specifies the IBM Connect:Direct node where the statement executes. The default is pnode.

pnodeid = (id [, pswd])

specifies security user IDs and passwords for the pnode. Each parameter value can be 1-20 alphanumeric characters long.

id specifies the user ID to be used as a security ID on the pnode. This must be the name of an existing user account. It is not case-sensitive.

pswd specifies a user password on the pnode. It is case-sensitive.

If pswd is specified, id must be specified also. These values must be specified in the order shown.

When copying to a file server other than the one containing IBM Connect:Direct, pnodeid is required.

Process name

The Process name is a user-defined 1-8 character alphanumeric string. It must begin in position one. You cannot use a statement name, parameter name, or subparameter name as the Process name. This field is required on the Process statement. The process keyword must be on the same line as the Process name.

prty = nn

specifies the selection priority of the Process in the Transmission Control Queue (TCQ). A Process with a higher priority is selected for execution before a Process with a lower priority. This value does not affect the priority during execution.

Values range from 0-15. The highest priority is 15. If prty is not specified, the value from proc.prio.default in the initialization parameters is used. If no value is specified in the initialization parameters, the default is 10.

remoteacct = “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 remoteacct parameter on the copy statement overrides the accounting data specified on the process statement.

restart(yes) | restart(no)

specifies whether a program runs again after a session failure. This value overrides the value set in the initialization parameter.

retain = yes | no | initial

specifies whether the Process is retained in the TCQ after execution.

yes specifies that the Process is retained in HR status after execution. A Process submitted with retain=yes remains in the TCQ after execution until:

it is explicitly released through the change process command)
Until the time specified in the startt parameter is reached
Until the Process is deleted through the delete process command

Processes submitted with both retain=yes and startt are cloned. If startt specifies both day of the week and a time, the cloned Process runs every week on that day and at that time. If startt specifies day only, the cloned Process runs every week on that day at 12:00 a.m. If startt specifies time only, the cloned Process runs every day at that time.

no specifies that the Process is deleted immediately after execution. This is the default value.

initial specifies that the Process is retained in the Hold queue and automatically executes each time the Connect:Direct for Microsoft Windows server initializes.

Processes submitted with retain=initial are only searched for when the server initially starts. At that time, they are cloned, and the clone executes immediately.

Note the following:

The Submit command fails if you specify both the startt parameter and the retain=initial parameter.
When a Process is submitted with retain=yes and hold=no or hold=call, the hold parameter is ignored.

snode = [nodename] | [hostname | IPaddress;portnumber|servicename]

is a 1-16 alphanumeric character string that specifies the IBM Connect:Direct snode name. This parameter is required on either the submit command or the process statement.

nodename is the node name of the IBM Connect:Direct snode. The snode name corresponds to a IBM Connect:Direct remote.node object in the network map.

hostname is the name of the host machine where the IBM Connect:Direct snode is running. This is applicable only for TCP/IP.

IPaddress is the IP address of the IBM Connect:Direct snode. The IP format is nnn.nnn.nnn.nnn. Each nnn is a decimal number from 0-255, inclusive. This is applicable only for TCP/IP.

portnumber|servicename identifies the communications port for the IBM Connect:Direct software. The portnumber is a decimal number from 1024-65535. This is applicable only for TCP/IP.

The snode parameter on the copy statement overrides the value specified in the process statement.

snodeid = (id [,pswd[,newpswd]])

specifies security user IDs and security passwords for the Process on the snode. Each snodeid parameter value can be 1-20 alphanumeric characters. When copying to a file server other than the one containing IBM Connect:Direct, snodeid is required.

id specifies the user ID used as a security ID on the snode.

pswd specifies the user password on the snode.

newpswd specifies a new password value. The user password is changed to the new value on the snode if the user ID and old password are correct and the snode supports this optional parameter. The newpswd parameter is not valid if the snode is a Connect:Direct for Microsoft Windows node.

If snodeid is specified, id must be specified also. If newpswd is specified, pswd must be specified also. Specify these values in the order of id, pswd, and newpswd.

For IBM Connect:Direct HP NonStop nodes, snodeid specifies the HP NonStop group number and user number. The valid range for these numbers is 0-255

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)

startt = ([date | day] [,time [am | pm]])

specifies that the Process executes at a specific date and time. The Process is placed in the Timer queue in WS status. The date, day, and time values are positional subparameters. If you do not specify date or day , precede time with a comma.

CAUTION:

Do not specify the startt parameter and the retain=initial parameter. This will cause the submit command to fail.

date specifies that the Process will execute on a specific date. The current date is the default. Specify the date subparameter in the format mm/dd/yyyy or mm-dd-yyyy, where:

mm indicates month and can be a one- or two-digit number
dd indicates day and can be a one- or two-digit number
yyyy indicates year and can be a two- or four-digit number

day specifies the day of the week that the Process will execute. Values are today, tomorrow, monday, tuesday, wednesday, thursday, friday, saturday, and sunday.

time specifies the time the Process will start. The format is hh:mm:ss [am|pm] where (hh) specifies the hour, (mm) the minute, and (ss) the second the Process will start. Hour may be specified in either 12- or 24-hour format. If the 12-hour format is used, then am or pm must be specified. Seconds (ss) are optional. A space is required before am or pm. The default is 24-hour format. The default value is 00:00:00, which indicates midnight.

If only day or date is specified, time defaults to 00:00:00 (midnight). 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 at midnight.

When both hold=yes and a startt value are specified, the hold specification takes precedence. A Process submitted with hold=yes is placed in the Hold queue even if a start time is specified.

subnode = pnode | snode

specifies whether the Process should be submitted to the pnode, the node where the Process currently executing was submitted, or to the snode, the current executing session partner of the Process.

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

is a symbolic parameter assigned a value. The value is substituted within the Process when the symbolic parameter is encountered. You can override this value when you submit the Process.

The following built-in variables can be used for the symbolic variable values; they must be enclosed in double quotation marks:

Value	Description
%JDATE	Specifies the date the Process was submitted in Julian format. The variable is resolved as the submission date of the Process in the format yyyyddd. Among other uses, the value returned is suitable for constructing a file name on the node receiving the file. The value of the variable is resolved at Process submit time. The value will correspond to the date on which the Process was submitted, regardless of when or how many times the Process is actually executed.
%NUM1	Specifies the submission time of the Process in minutes, seconds, and fraction of seconds in the format mmssth.
%NUM2	Specifies the submitted time of a Process as the low order 4 bits of the milliseconds of the time expressed as 1 hex digit (a value from 0 through 15 expressed as 0 through F).
%PNODE	PNODE name where the submit occurs
%PRAND	Pseudo-random number (6 hex digits)
%SUBDATE	Specifies the date the Process was submitted in Gregorian format. The variable is resolved as the submission date of the Process in the format cyymmdd where c is the century indicator and is set to 0 for year 19yy or 1 for year 20yy. The value returned can be used to create a file name on the node receiving the file.
%SUBDATE1	Use this parameter to substitute the submitted date in the yyyymmdd date format.
%SUBDATE2	Use this parameter to substitute the submitted date in the yyyyddmm date format.
%SUBDATE3	Use this parameter to substitute the submitted date in the mmddyyyy date format.
%SUBDATE4	Use this parameter to substitute the submitted date in the ddmmyyyy date format.
%SUBTIME	Specifies the time the process was submitted. The variable is resolved as the submission time of the process in the format hhmmss. The return value can be used to create a file name on the node receiving the file. The value of the variable is resolved at Process submit time. The value will correspond to the time at which the Process was submitted, regardless of when or how many times the Process is actually executed.
%USER	Specifies a variable that resolves to the user submitting the Process

Do not use statement names, parameter names, and subparameter names as symbol names.

Enclose symbolic parameter value in double quotation marks if it is a parameter, subparameter, or statement name or if it contains special characters. It can be set to a single ampersand symbolic parameter that was resolved during a previous Process submission. Do not use identical symbolic names.

sysopts=fld1(val1) fld2(val2) ...fldn(valn)

specifies system-specific parameters on the copy statement. The parameters are a series of field names and values fldn(valn), each of which is delimited by a space. The entire string is enclosed in double quotes. For example:

“xlate(yes) xlate.tbl(tbl1)”

The sysopts subparameters are:

datatype(text|binary) specifies the type of data contained within the file.

text indicates it is a text file and that trailing blanks will be stripped unless you specify strip.blanks(no). Translation of the data is performed unless you also specify xlate(no). The default is text for all nodes, except Microsoft Windows nodes. The following list shows the default source file attributes assigned for Microsoft Windows text files, which are used if necessary by the remote IBM Connect:Direct node:
dsorg=ps (physical sequential organization)
recfm=vb (variable-length records, blocked if the destination operating system supports it)
lrecl=23036 (maximum record length of 23036)
blksize=23040 (maximum block size of 23040, if the destination operating system supports record blocking)
binary indicates the file contains binary data. The default is binary for Microsoft Windows nodes. The following shows the default source file attributes assigned for Microsoft Windows binary files, which are used if necessary by the remote IBM Connect:Direct node:
dsorg=ps (physical sequential organization)
recfm=u (undefined record format)
lrecl=0 (undefined record length)
blksize=23040 (maximum block size and record size of 23040)

user_data specifies any user-defined data to be passed to the open exit dynamic link library (DLL) specified by the user, when the file is opened. The value defined for user_data is limited to a maximum of 511characters and cannot contain a closing parenthesis ‘)’ character.

Note: The file open exit DLL is defined in the IBM Connect:Direct initialization parameters.

strip.blanks(yes | no) determines whether trailing blank characters at the end of each record are removed from a line of text before it is written to the Microsoft Windows text file.

Note: The strip.blanks parameter is ignored when datatype(binary) is specified.

yes removes trailing blank characters. The default is yes for UNIX, Microsoft Windows, z/OS, VM, VSE, and i5/OS nodes.
no does not remove trailing blank characters. The default is no for all nodes except UNIX, Microsoft Windows, z/OS, VM, VSE, and i5/OS.

strip.oneable(yes | no) strips ^Z from the end of old DOS files. If this character is not stripped from old DOS files, Connect:Direct for Microsoft Windows translates ^Z into 3F when files are sent to the snode.

yes removes ^Z from the end of old DOS files.
no does not remove ^Z from the end of old DOS files. This is the default value.

Because this parameter applies to text file transfers only, be sure to specify datatype (text) and strip.oneable (yes) in sysopts to strip the character from the end of the DOS file.

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 should not be performed. The default for Microsoft Windows and all other nodes with the exception of z/OS, VM, VSE, and i5/OS is no.
yes specifies the translation should be performed. The default for z/OS, VM, VSE, and i5/OS nodes is yes.

xlate.tbl(pathname/filename) specifies that a different translation table from the default table used by IBM Connect:Direct is used. pathname/filename should identify a translation table created using the translation table editor of the IBM Connect:Direct Requester for Microsoft Windows. The path specification is optional. If the path is not provided, the path specified by the xlate.dir initialization parameter is assumed for the filename specified.

codepage=(source codepage, destination codepage)

The sysopts subparameters valid only in the to clause are:

acl(operation,rightslist,accountname
[;operation,rightslist,accountname[;operation,rightslist,
accountname[;...]]) specifies the users or groups allowed or denied access to a file being created by the copy operation. This subparameter is ignored if specified for a file that already exists.

operation specifies whether the rights are allowed or denied. Valid values are:

allow
deny
rightslist specifies the type of rights allowed or denied. Valid values are:
read
write
execute
delete
all
The rights values can be combined by linking them with the + sign.

accountname specifies the name of the user or group to which access is allowed or denied. Multiple-user rights may be specified with each group enclosed in parentheses and delimited by a comma.

attributes(physattr) specifies the physical attributes of the file when it is created.

physattr can include the following attributes (case sensitive):

A (Archive Needed)
H (Hidden)
R (Read Only)
S (System)

sysopts=”pgm(filespec) cmd(command | parms) args(arguments) | desktop (yes | no)”

specifies the parameters for the operation being performed by the run job statement. This field is required.

Possible values are:

pgm(filespec) specifies which .EXE or .BAT file will be run.

Note: You must use either the pgm or cmd parameter. Do not specify both.

cmd(command | parms) specifies a system command and any arguments that this command requires.

args(arguments) specifies the arguments passed to the program when it is started. These arguments are in the same format as they would be specified from the command prompt. This optional parameter is only valid when you specify pgm.

desktop(yes | no) specifies whether you want to interact with the desktop. The default for the desktop parameter is no when used with the run job statement. This optional parameter is only valid when specified with pgm or cmd.

to

specifies the parameters and subparameters that define the destination file characteristics. This field is required.

SECMODEL = (profile-name [,GENERIC])

copies an existing Resource Access Control Facility (RACF) profile as the discrete profile for a new data set. The following information is copied along with the profile: OWNER, ID, UACC, AUDIT/GLOBALAUDIT, ERASE, LEVEL, DATA, WARNING, and SECLEVEL.

profile-name is the name of the model RACF profile, discrete data set profile, or generic data set profile to be copied to the discrete data set profile created for the new data set.

GENERIC identifies that the profile-name refers to a generic data set profile.