Sterling Connect:Direct CopyTo Service

Edit online

This is an overview of the Sterling Connect:Direct Server CopyTo service:

System Name Sterling Connect:Direct® Server CopyTo Service
Graphical Process Modeler (GPM) categories All Services, Applications > IBM > IBM® Sterling Connect:Direct
Description This service copies a document to a remote Sterling Connect:Direct server. To ensure that the copy performed by this service can restart from the last checkpoint if a crash interrupts the copy operation, set the recovery level to Auto-resume for the business process that uses the CopyTo service and specify a checkpoint interval for that service. If so marked, the business process and the copy are resumed automatically when Sterling B2B Integrator restarts, if the remote Sterling Connect:Direct node is still active. When resumed, the copy is restarted from the last checkpoint.
Business usage A business user would use this service to copy a document to a remote Sterling Connect:Direct.
Usage example A trading partner copies a business document to a remote Sterling Connect:Direct server outside the organization.
Preconfigured? Yes
Requires third party files? No
Platform availability All supported platforms
Related services When the Sterling Connect:Direct Server CopyTo service is used in a business process, the Sterling Connect:Direct Server Primitive CopyTo service is exercised behind the scenes as part of a system business process to perform the actual copy operation.

The Sterling Connect:Direct Server CopyTo service has tight integration with the Sterling Connect:Direct Server Begin Session service. A session must be established between two Sterling Connect:Direct nodes using the Begin Session service in order to execute the CopyTo service successfully. The Sterling Connect:Direct Server End Session service must be used to end the session established between the Sterling Connect:Direct nodes after the Sterling Connect:Direct Server CopyTo service.
Application requirements For more information, search for Requirements
Initiates business processes? No
Invocation A user who has permission to perform this activity must start the business process that runs this service.
Business process context considerations LocalStripBlanks and LocalXlate are optional parameters. Use these parameters only when you want to control non-standard behavior and you have a complete understanding of your environment, the local content, the target requirement, data translation, and character set conversion.

If LocalStripBlanks and LocalXlate are not explicitly assigned in the business process (see example below), the settings are determined automatically.

Example of a BP that does not explicitly assign LocalStripBlanks and LocalXlate parameters:

    <operation name="CD Server Copy To Service">
      <participant name="ConnectDirectServerCopyToService001"/>
      <output message="CopyTo">
        <assign to="." from="*"></assign>
        <assign to="RemoteFileName">purchase-order.txt</assign>
      </output>
      <input message="inmsg">
        <assign to="CopyToResults" from="*"></assign>
      </input>
    </operation>

If LocalStripBlanks and LocalXlate are explicitly assigned in the business process (see example below), the business process controls the translation and the specified values are used.

Returned status values
  • Success – Normal execution with the return parameters specified.

Advanced Errors

  • Invalid Document Error – Business process does not have document to be copied to a target Sterling Connect:Direct server.
  • CopyTo Remote File Error – An error related to file on remote Sterling Connect:Direct server. Might the file error or file path is invalid or invalid file permissions.
  • Invalid Sysopts Error – Sysopts may contain invalid syntax or characters
  • Sterling Connect:Direct Server Error – Generic error associated with the Sterling Connect:Direct server has occurred.
  • Sterling Connect:Direct Error – Generic error associated with the Sterling Connect:Direct server has occurred.
  • Sterling Connect:Direct Service Error – Generic error associated with this service has occurred.
Restrictions Sterling B2B Integrator version 5.1 and later supports the most common set of parameters available in the Sterling Connect:Direct for z/OS® Process Copy statement To clause to provide more functionality, such as enhanced file allocation and disposition options for the destination file on the remote Sterling Connect:Direct for z/OS node. To ensure that business processes created in earlier versions of Sterling B2B Integrator continue to execute properly, parameters existing in versions 5.0 and earlier will still be supported. However, these old parameters cannot be mixed with new parameters in the same CopyTo service.

Use the new parameters when you create a new business process and when you make upgrade an existing CopyTo service.

Persistence level None
Testing considerations Debug information is found in the Sterling Connect:Direct Interop log files.

Implementing the Sterling Connect:Direct Server CopyTo Service

To implement the Sterling Connect:Direct Server CopyTo Service:
  1. Create a Sterling Connect:Direct Server adapter to be used with this service.
  2. Configure the Sterling Connect:Direct Server CopyTo service.
  3. Use the Sterling Connect:Direct Server CopyTo service in a business process.

The Enhanced Set of Connect:Direct CopyTo Parameters

Note: For users familiar with the Sterling Connect:Direct Process language, the parameters with the Remote prefix are equivalent to the parameters specified in the COPY TO clause of a COPY statement and refer to the destination file being copied to the Sterling Connect:Direct node. The parameters with the Local prefix correspond to the parameters specified in the COPY FROM clause and refer to the source file on the Sterling B2B Integrator CDSA node.

When you create a new business process using BPML code written in a text editor or use the graphical interface tool available in Sterling B2B Integrator, Graphical Process Modeler (GPM), make sure that the CopyTo Service contains only “old” parameters or “new” parameters—do not mix parameters from both columns. For example, do not include DCB unittype and RemoteUNIT in the same CopyTo service. Replacements for old DCB parameters are noted in the table, for example, instead of coding DCB expirationdate, use RemoteLABEL EXPDT.

In addition, you can find several CopyTo service examples illustrating the values and syntax valid for the Sterling Connect:Direct platform you copy to, including UNIX, Microsoft Windows, and i5/OS.

This table lists the old parameters available in Sterling B2B Integrator version 5.0 and earlier and the new parameters available in Sterling B2B Integrator version 5.1 and later that give you more file handling capabilities and more closely match the Process language and syntax of Sterling Connect:Direct for z/OS. The new parameters are indicated in the table with an asterisk and have a prefix of Remote to indicate the remote Sterling Connect:Direct node to which the local Sterling Connect:Direct Service adapter is transferring a file.

Old Parameter/Syntax New Parameter/Syntax for z/OS
DCB

[,blocksize=no.-bytes]

[,datasetorganization =[PS | PO]

[,recordlength=no.-bytes]

[,recordformat=record-format]

[unittype=unit-address | device-type | group-name] ,

[unit-count | P ]

Note: Use the new RemoteUNIT parameter as shown in Connect:Direct Server CopyTo Service Settings.

[expirationdate=yyddd | yyyy/ddd]

Note: Use EXPDT=[yyddd | yyyy/ddd] in the new RemoteLABEL parameter.

[retentionperiod=nnnn]

Note: Use [RETPD=nnnn | EXPDT] in the new RemoteLABEL parameter.

[volumecount=maximum-no.-files-required-by-an-

output file]

Note: Use the new RemoteVOL parameter.
 RemoteDCB

([model-file-name]

[,BLKSIZE=no.-bytes]

[,DEN=0 | 1 | 2 |3 | 4]

[,DSORG=[PS | PO | DA | VSAM]

[,KEYLEN=no.-bytes]

[,LIMCT=no.-blocks-or-tracks]

[,LRECL=no.-bytes]

[,OPTCD=W | Q | Z]

[,RECFM=record-format]

[,RKP=first-byte-position-of-record-key]

)
CDDisposition

new | old | rpl

Note: Use the new RemoteDISP parameter as shown in Connect:Direct Server CopyTo Service Settings.
 RemoteDISP

([NEW | OLD | MOD | RPL | SHR],

[KEEP | CATLG] ,

[KEEP | CATLG | DELETE]

)

|

(NEW | OLD | MOD | RPL | SHR)

|

NEW | OLD | MOD | RPL | SHR
  RemoteSMS

AVGREC=U | K | M

DATACLAS=data-class-name

DSNTYPE=PDS | LIBRARY | LARGE | EXTREQ |

     EXTPREF | BASIC

KEYLEN=length in bytes

KEYOFF=offset-to-key

LIKE=model-data-set-name

LRECL=number of bytes

MGMTCLAS=management-class-name

RECORG=KS | ES | RR | LS

SECMODEL=(profile-name [,GENERIC])

STORCLAS=storage-class-name
  RemoteLABEL

([file-sequence-number]

,[SL | AL | BLP | LTM | NL | AUL | NSL | SUL]

,[PASSWORD | NOPWREAD]

,[IN | OUT]

,[RETPD=nnnn | EXPDT=[yyddd | yyyy/ddd]]

)

Note: RETPD and EXPDT were coded in the old DCB parameter.
  RemoteMSVGP
  RemoteSPACE
  RemoteUNIT
Note: This was coded in the old DCB parameter.
  RemoteVOL
Note: This was coded in the old DCB parameter.
  RemoteBUFND
  RemoteIOEXIT
  RemoteDATAEXIT
Sysopts Sysopts
RemoteFileName RemoteFileName
LocalFileNameLabel LocalFileNameLabel
Compression Compression
LocalFromCodePage LocalFromCodePage
LocalToCodePage LocalToCodePage
LocalXlate LocalXlate
LocalStripBlanks LocalStripBlanks
LocalDocumentId LocalDocumentId
BinaryMode BinaryMode
CDRecordType CDRecordType
CheckpointInterval CheckpointInterval
SessionToken SessionToken

Sterling Connect:Direct Server CopyTo Service Settings

To configure the Sterling Connect:Direct Server CopyTo Service, specify the following fields in the GPM.

Field Description
AutoDetectTerminator Specifies whether or not to automatically identify the line terminator of a file in TEXT format instead of assuming the line terminator based on the CDSA host platform. Optional.

Files stored in TEXT format have different line terminators depending on the host platform. UNIX or Linux platforms terminate TEXT lines using the LF (Line Feed) character (value=0x0a), whereas Windows platforms terminate TEXT lines using a pair of CR and LF (Carriage Return/Line Feed) characters (value=0x0c0a). As a result, interoperability issues can arise if a Windows-formatted file is transferred to a UNIX or Linux platform in BINARY mode and then the same file is transferred from the UNIX or Linux platform in TEXT mode. The AutoDetectTerminator parameter, when enabled, ensures that such issues do not arise by automatically detecting the line terminator of the TEXT file.

Valid values are:
  • Yes—Automatically detect the line terminator of a text file. Default.
  • No—Does not automatically detect the line terminator of a text file.
BinaryMode Specifies how the data from the source file on the local Sterling Connect:Direct Server adapter node will be transferred to the remote Sterling Connect:Direct node. Optional.

Valid values are:

  • Yes—File will be transferred in simple binary mode.
  • No—File will not be transferred in binary mode but rather in text mode. Default.
  • VB—Copy will be performed as a variable block binary transfer with Sterling Connect:Direct on the z/OS platform.
CDDisposition Specifies how the file gets created on the remote Sterling Connect:Direct server. Optional. Valid values are:
  • New – Specifies that the CopyTo service will create the destination file. The copy fails if the file exists
  • rpl – Specifies that the destination file name replaces any existing file or, if none exists, allocates a new file
    Note: Only use this parameter with existing business processes created in Sterling B2B Integrator version 5.0 or earlier. Use the RemoteDISP parameter instead.
CDRecordType Entry name of the type defaults file. The type defaults file contains the default file attributes used to allocate the destination file. The type defaults file is specified only when defaults are requested by the user. Optional. For more information on the type defaults file, refer to the IBM Sterling Connect:Direct for z/OS user documentation.
CheckpointInterval 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. Optional.

Valid value is number of bytes, in one of the following formats:

  • nnnnnnnnnn
  • nK or nM
  • nm or nk
Compression 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. Optional. Valid values are 1-9. Increasing the value indicates a greater attempt at compression and will consume more CPU. Values greater than 2 may not result in further compression.
Config Name of the service configuration. Required.
DCB Specifies Data Control Block (DCB), a group of attributes specified as name-value pairs separated by commas. One, some, or all values may be included. Pattern is name=value with comma between, as in the following example:

recordlength=200, blocksize=2000, recordformat=FB, datasetorganization=PS, unittype=cart, expirationdate=06365, volumecount=99

Used only on the z/OS platform. Optional. Valid attributes are:

  • recordlength
  • blocksize
  • recordformat
  • datasetorganization
  • expirationdate (Use EXPDT=[yyddd | yyyy/ddd] in the RemoteLABEL parameter to replace this attribute.)
  • volumecount (Use the RemoteVOL parameter to replace this attribute.)
  • unittype (Use the RemoteUNIT parameter to replace this attribute.)
    Note: Additional DCB attributes are available but only these are supported using this old parameter in Sterling B2B Integrator. Any other attribute will cause the copy to fail. For more functionality and additional file allocation options, use the RemoteDCB parameter.

For more information on DCB in general, refer to the IBM Sterling Connect:Direct for z/OS documentation.

Note: This is an “old” parameter, which should only be used in existing business processes created in Sterling B2B Integrator Version 5.0 or earlier. Use the RemoteDCB parameter instead.
LocalDocumentId A valid document ID for an existing document in Sterling B2B Integrator. When this field is left blank, the primary document provided to the business process is used. Optional.
LocalFileNameLabel Specifies a label for the name of the local file. This file name label is provided to the remote Sterling Connect:Direct node for informational purposes only. Optional.
LocalFromCodePage Specifies a code page supported by Java VM. Used in conjunction with the value of the LocalToCodePage parameter. The Sterling Connect:Direct Server adapter will apply a code page conversion to a document before transferring it to a remote Sterling Connect:Direct server. This parameter is only valid with the following conditions:
  • Code page specified is supported by the local Java VM
  • Parameter LocalToCodePage is defined
  • Text mode file transfer (BinaryMode =No)

Optional. Valid value is the name of a codepage supported by the local Java VM.

For example:

<assign to="LocalFromCodePage">Cp1251</assign>

<assign to="LocalToCodePage">Cp1047</assign>

This example will translate the local file from windows latin-1 to ibm ebcdic. See http://java.sun.com for supported encodings.
LocalStripBlanks Specifies whether the Sterling Connect:Direct Server adapter will strip blanks from the end of records in the local file before sending them to the remote node. This option is only valid for Text mode file transfers (BinaryMode = No). Optional. Valid value is Yes or No (default).
LocalToCodePage Specifies a code page supported by Java VM. Used in conjunction with the value of the LocalFromCodePage parameter. The Sterling Connect:Direct Server adapter will apply a code page conversion to a document before transferring it to a remote Sterling Connect:Direct Server. This parameter is only valid with the following conditions:
  • Code page specified is supported by the local Java VM
  • Parameter LocalFromCodePage is defined
  • Text mode file transfer (BinaryMode =No)

Optional. Valid value is the name of a codepage supported by the local Java VM.

For example:

<assign to="LocalFromCodePage">Cp1251</assign>

<assign to="LocalToCodePage">Cp1047</assign>

This example will translate the local file from windows latin-1 to ibm ebcdic. See http://java.sun.com/ for supported encodings.
LocalXlate Specifies if the Sterling Connect:Direct Server adapter is to perform ASCII to EBCDIC translation before copying a file to a remote Sterling Connect:Direct Server. This option is only valid for Text mode file transfers (BinaryMode = No). Optional. Valid value is Yes (default) or No.
RemoteBUFND Specifies the number of I/O buffers VSAM will use for transmitting data between virtual and auxiliary storage. Optional.

Used only on the z/OS platform.

For more information on how to specify BUFND information, refer to the IBM Sterling Connect:Direct for z/OS documentation.
RemoteDATAEXIT Specifies a user-written program through which data is processed before being written to the destination file. Optional.

Used only on the z/OS platform. Valid syntax is:

exit-name | (exit-name [,parameter,...])

For more information on dataexits, refer to the IBM Sterling Connect:Direct for z/OS user documentation.
RemoteDCB Specifies Data Control Block (DCB), a group of attributes to be used in allocating destination files on a z/OS system.

Used only on the z/OS platform. Optional. Valid attributes are:

([model-file-name]

[,BLKSIZE=no.-bytes]

[,DEN=0 | 1 | 2 |3 | 4]

[,DSORG=[PS | PO | DA | VSAM]

[,KEYLEN=no.-bytes]

[,LIMCT=no.-blocks-or-tracks]

[,LRECL=no.-bytes]

[,OPTCD=W | Q | Z]

[,RECFM=record-format]

[,RKP=first-byte-position-of-record-key]

)

For information on DCB attributes, refer to the IBM Sterling Connect:Direct for z/OS documentation.
RemoteDISP Specifies how the destination file is to be created on the remote Sterling Connect:Direct server. Optional.

Valid syntax for Sterling Connect:Direct for z/OS is:

([NEW | OLD | MOD | RPL | SHR],

[KEEP | CATLG] ,

[KEEP | CATLG | DELETE]

)

|

(NEW | OLD | MOD | RPL | SHR)

|

NEW | OLD | MOD | RPL | SHR

For more information on the values and syntax valid for the Sterling Connect:Direct platform you are copying to, refer to your IBM Sterling Connect:Direct for z/OS documentation.
RemoteFileName Name that should be given to the destination file that is copied to the remote Sterling Connect:Direct server. Required.

If the remote Sterling Connect:Direct server is a Sterling B2B Integrator - Sterling Connect:Direct Server Adapter, use the following general syntax if you copy to a mailbox:

/mailbox/yourMailbox/yourDestinationFile

There are three parts to the RemoteFileName:
  • mailbox is a reserved word and signals to Sterling B2B Integrator that you are copying to a Mailbox.
  • yourMailbox is the name of your Sterling B2B Integrator Mailbox.
  • yourDestinationFile is the document that is passed to your mailbox by the Sterling Connect:Direct Server Adapter. This document is stored in the mailbox. This document can be retrieved by an SFTP client, business process or another Sterling Connect:Direct Process.

If the remote Sterling Connect:Direct server is a Sterling B2B Integrator - Sterling Connect:Direct Server Adapter, use the following general syntax if you copy to a business process:

/businessprocess/yourBusinessProcess/yourDestinationFile

There are three parts to the RemoteFileName:
  • /businessprocess/ is a reserved word and signals to Sterling B2B Integrator that you are copying to a business process.
  • yourBusinessProcess is the name of the Sterling B2B Integrator business process that the Sterling Connect:Direct Server Adapter invokes.
  • yourDestinationFile is the name of the document that is passed to the business process by the Sterling Connect:Direct Server Adapter. This document becomes the Primary Document in the yourBusinessProcess business process.
Note: You cannot use wildcards to copy multiple files from Sterling B2B Integrator to Sterling Connect:Direct with a single CopyTo service.
RemoteIOEXIT Specifies a user-written program to be invoked to perform I/O requests on the source file before copying the source file to a destination file. Optional.

Used only on the z/OS platform. Valid syntax is:

exit-name | (exit-name [,parameter,...])

For more information on I/O exits, see the IBM Sterling Connect:Direct for z/OS user documentation.
RemoteLABEL Specifies label information for the tape used for the destination file. Optional.

Used only on the z/OS platform. Valid syntax is:

([file-sequence-number]

,[SL | AL | BLP | LTM | NL | AUL | NSL | SUL]

,[PASSWORD | NOPWREAD]

,[IN | OUT]

,[RETPD=nnnn | EXPDT=[yyddd | yyyy/ddd]]

)

For more information on how to specify label information, see the IBM Sterling Connect:Direct for z/OS documentation.

Note: The Retention Period (RETPD) and Expiration Date (EXPDT) attributes were coded in the old DCB parameter.
RemoteMSVGP Specifies the group of mass storage volumes that reside on a mass storage system (MSS) device. This must be a valid DD (data definition) name, ranging from 1-8 alphanumeric characters with the first character alphabetic. Optional.

Used only on the z/OS platform. Valid value is MS-group-name.
RemoteSMS Specifies SMS attributes to use when creating the destination file. Optional.

Used only on the z/OS platform. Valid attributes are:

  • AVGREC=U | K | M
  • DATACLAS=data-class-name
  • DSNTYPE=PDS | LIBRARY | LARGE | EXTREQ | EXTPREF | BASIC
  • KEYLEN=length in bytes
  • KEYOFF=offset-to-key
  • LIKE=model-data-set-name
  • LRECL=number of bytes
  • MGMTCLAS=management-class-name
  • RECORG=KS | ES | RR | LS
  • SECMODEL=(profile-name [,GENERIC])
  • STORCLAS=storage-class-name

For more information on SMS attributes, see the IBM Sterling Connect:Direct for z/OS user documentation.
RemoteSPACE Specifies the amount of storage to be allocated for new files on the destination node. If SPACE is specified, the RemoteDISP of the destination file must be NEW or RPL. Optional.

Used only on the z/OS platform. Valid syntax is:

(CYL | TRK | blk,

(prim , [sec] , [dir]), [RLSE] , [CONTIG] , [ROUND]) |

(av-rec-len , (primary-rcds , [secondary-rcds] , [dir])

)

For more information on how to specify SPACE information, see the IBM Sterling Connect:Direct for z/OS user documentation.
RemoteUNIT Specifies the storage device or type along with the number of devices required. Optional.

Used only on the z/OS platform. Valid syntax is:

([unit-address | device-type | group-name], [unit-count | P ] [,DEFER])

For more information on how to specify UNIT information, see the IBM Sterling Connect:Direct for z/OS user documentation.

Note: Unittype was coded in the old DCB parameter.
RemoteVOL Specifies one or more volume serial numbers containing the destination file and optional processing associated with the file. Optional.

Used only on the z/OS platform. Valid syntax is:

([PRIVATE],[RETAIN]

,[volume-sequence-no] ,[volume-count]

[,SER=(serial-no [,serial-no,...])

|SER=serial-no)

|([SER=(serial-no ,[serial-no,...]))

|(REF=dsn])

For more information on how to specify VOL information, see the IBM Sterling Connect:Direct for z/OS user documentation.

Note: Volumecount was coded in the old DCB parameter.
SessionToken Identifies an established session between two Sterling Connect:Direct nodes. Required. Session integrity cannot be guaranteed if the session token is omitted.
Sysopts Remote system operations to be implemented on the remote Sterling Connect:Direct node. Optional.

For example (for copying to Sterling Connect:Direct for Windows only):

Datatype(text) xlate(yes)

For more information, see IBM Sterling Connect:Direct documentation.

Parameters Passed from Business Process to a CopyTo Service

This table describes the parameters passed from the business process to the Sterling Connect:Direct CopyTo service:

Field Description
AutoDetectTerminator Specifies whether or not to automatically identify the line terminator of a file in TEXT format instead of assuming the line terminator based on the CDSA host platform. Optional.

Files stored in TEXT format have different line terminators depending on the host platform. UNIX or Linux platforms terminate TEXT lines using the LF (Line Feed) character (value=0x0a), whereas Windows platforms terminate TEXT lines using a pair of CR and LF (Carriage Return/Line Feed) characters (value=0x0c0a). As a result, interoperability issues can arise if a Windows-formatted file is transferred to a UNIX or Linux platform in BINARY mode and then the same file is transferred from the UNIX or Linux platform in TEXT mode. The AutoDetectTerminator parameter, when enabled, ensures that such issues do not arise by automatically detecting the line terminator of the TEXT file.

Valid values are:
  • Yes—Automatically detect the line terminator of a text file. Default.
  • No—Does not automatically detect the line terminator of a text file.
BinaryMode Specifies how the data from the source file on the local Sterling Connect:Direct Server adapter node will be transferred to the remote Sterling Connect:Direct node. Optional.

Valid values are:

  • Yes—file will be transferred in simple binary mode
  • No—file will not be transferred in binary mode but rather in text mode (default)
  • VB—copy will be performed as a variable block binary transfer with Sterling Connect:Direct on the z/OS platform
CDDisposition Specifies how the file gets created on the remote Sterling Connect:Direct server. Optional. Valid values are:
  • New – Specifies that the CopyTo service will create the destination file. The copy fails if the file exists
  • rpl – Specifies that the destination file name replaces any existing file or, if none exists, allocates a new file
    Note: This parameter should only be used in existing business processes created in Sterling B2B Integrator Version 5.0 or earlier. Use the RemoteDISP parameter instead.
CDRecordType Specifies the entry name of the type defaults file. The type defaults file contains the default file attributes used to allocate the destination file. The typekey is specified only when defaults are requested by the user. Optional. For more information on the type defaults file, see the IBM Sterling Connect:Direct for z/OS user documentation.
CheckpointInterval 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. Optional.

Valid value is number of bytes, in one of the following formats:

  • nnnnnnnnnn
  • nK or nM
  • nm or nk
Compression 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. Optional. Valid values are 1-9. Increasing the value indicates a greater attempt at compression and will consume more CPU. Values greater than 2 may not result in further compression.
Config Name of the service configuration. Required.
DCB Specifies Data Control Block (DCB), a group of attributes specified as name-value pairs separated by commas. One, some, or all values may be included. Pattern is name=value with comma between, as in the following example:

recordlength=200, blocksize=0, recordformat=FB, datasetorganization=PS, unittype=cart, expirationdate=06365, volumecount=99

Used only on the z/OS platform. Optional. Valid attributes are:

  • recordlength
  • blocksize
  • recordformat
  • datasetorganization
  • expirationdate (Use EXPDT=[yyddd | yyyy/ddd] in the RemoteLABEL parameter to replace this attribute.)
  • volumecount (Use the RemoteVOL parameter to replace this attribute.)
  • unittype (Use the RemoteUNIT parameter to replace this attribute.)
    Note: Additional DCB attributes are available but only these are supported using this old parameter in Sterling B2B Integrator. Any other attribute will cause the copy to fail. For more functionality and additional file allocation options, use the RemoteDCB parameter.

For more information on DCB in general, see the IBM Sterling Connect:Direct for z/OS user documentation.

Note: This parameter should only be used in existing business processes created in Sterling B2B Integrator Version 5.0 or earlier.
LocalDocumentId A valid document ID for an existing document in Sterling B2B Integrator. When this field is left blank, the primary document provided to the business process is used. Optional.
LocalFileNameLabel Specifies a label for the name of the local file. This file name label is provided to the remote Sterling Connect:Direct node for informational purposes only. Optional.
LocalFromCodePage Specifies a code page supported by Java VM. Used in conjunction with the value of the LocalToCodePage parameter. The Sterling Connect:Direct Server adapter will apply a code page conversion to a document before transferring it to a remote Sterling Connect:Direct server. This parameter is only valid with the following conditions:
  • Code page specified is supported by the local Java VM
  • Parameter LocalToCodePage is defined
  • Text mode file transfer (BinaryMode =No)

Optional. Valid value is the name of a codepage supported by the local Java VM.

For example:

<assign to="LocalFromCodePage">Cp1251</assign>

<assign to="LocalToCodePage">Cp1047</assign>

This example will translate the local file from windows latin-1 to ibm ebcdic. See http://java.sun.com/ for supported encodings.
LocalStripBlanks Specifies whether the Sterling Connect:Direct Server adapter will strip blanks from the end of records in the local file before sending them to the remote node. This option is only valid for Text mode file transfers (BinaryMode = No). Optional. Valid value is Yes or No (default).
LocalToCodePage Specifies a code page supported by Java VM. Used in conjunction with the value of the LocalFromCodePage parameter. The Sterling Connect:Direct Server adapter will apply a code page conversion to a document before transferring it to a remote Sterling Connect:Direct Server. This parameter is only valid with the following conditions:
  • Code page specified is supported by the local Java VM
  • Parameter LocalFromCodePage is defined
  • Text mode file transfer (BinaryMode =No)

Optional. Valid value is the name of a codepage supported by the local Java VM.

For example:

<assign to="LocalFromCodePage">Cp1251</assign>

<assign to="LocalToCodePage">Cp1047</assign>

This example will translate the local file from windows latin-1 to ibm ebcdic. See http://java.sun.com/for supported encodings.
LocalXlate Specifies if the Connect:Direct Server adapter is to perform ASCII to EBCDIC translation before copying a file to a remote Connect:Direct Server. This option is only valid for Text mode file transfers (BinaryMode = No). Optional. Valid value is Yes (default) or No.
RemoteBUFND Specifies the number of I/O buffers VSAM will use for transmitting data between virtual and auxiliary storage. Optional.

Used only on the z/OS platform.

For more information on how to specify BUFND information, see the IBM Sterling Connect:Direct for z/OS user documentation.
RemoteDATAEXIT Specifies a user-written program through which data is processed before being written to the destination file. Optional.

Used only on the z/OS platform. Valid syntax is:

exit-name | (exit-name [,parameter,...])

For more information on dataexits, see the IBM Sterling Connect:Direct for z/OS user documentation.
RemoteDCB Specifies Data Control Block (DCB), a group of attributes to be used in allocating destination files on a z/OS system.

Used only on the z/OS platform. Optional. Valid attributes are:

([model-file-name]

[,BLKSIZE=no.-bytes]

[,DEN=0 | 1 | 2 |3 | 4]

[,DSORG=[PS | PO | DA | VSAM]

[,KEYLEN=no.-bytes]

[,LIMCT=no.-blocks-or-tracks]

[,LRECL=no.-bytes]

[,OPTCD=W | Q | Z]

[,RECFM=record-format]

[,RKP=first-byte-position-of-record-key]

)

For more information on DCB attributes, see the IBM Sterling Connect:Direct for z/OS documentation.
RemoteDISP Specifies how the destination file is to be created on the remote Sterling Connect:Direct server. Optional.

Valid syntax for Sterling Connect:Direct for z/OS is:

([NEW | OLD | MOD | RPL | SHR],

[KEEP | CATLG] ,

[KEEP | CATLG | DELETE]

)

|

(NEW | OLD | MOD | RPL | SHR)

|

NEW | OLD | MOD | RPL | SHR

For more information on the values and syntax valid for the Sterling Connect:Direct platform you are copying to, see your IBM Sterling Connect:Direct for z/OS documentation.
RemoteFileName Name that should be given to the destination file that is copied to the remote Sterling Connect:Direct server. Required.
Note: You cannot use wildcards to copy multiple files from Sterling B2B Integrator to Sterling Connect:Direct with a single CopyTo service.
RemoteIOEXIT Specifies a user-written program to be invoked to perform I/O requests on the source file before copying the source file to a destination file. Optional.

Used only on the z/OS platform. Valid syntax is:

exit-name | (exit-name [,parameter,...])

For more information on I/O exits, see the IBM Sterling Connect:Direct for z/OS user documentation.
RemoteLABEL Specifies label information for the tape used for the destination file. Optional.

Used only on the z/OS platform. Valid syntax is:

([file-sequence-number]

,[SL | AL | BLP | LTM | NL | AUL | NSL | SUL]

,[PASSWORD | NOPWREAD]

,[IN | OUT]

,[RETPD=nnnn | EXPDT=[yyddd | yyyy/ddd]]

)

For more information on how to specify label information, see the IBM Sterling Connect:Direct for z/OS documentation.

Note: The Retention Period (RETPD) and Expiration Date (EXPDT) attributes were coded in the old DCB parameter.
RemoteMSVGP Specifies the group of mass storage volumes that reside on a mass storage system (MSS) device. This must be a valid DD (data definition) name, ranging from 1-8 alphanumeric characters with the first character alphabetic. Optional.

Used only on the z/OS platform. Valid value is MS-group-name.
RemoteSMS Specifies SMS attributes to use when creating the destination file. Optional.

Used only on the z/OS platform. Valid attributes are:

  • AVGREC=U | K | M
  • DATACLAS=data-class-name
  • DSNTYPE=PDS | LIBRARY | LARGE | EXTREQ | EXTPREF | BASIC
  • KEYLEN=length in bytes
  • KEYOFF=offset-to-key
  • LIKE=model-data-set-name
  • LRECL=number of bytes
  • MGMTCLAS=management-class-name
  • RECORG=KS | ES | RR | LS
  • SECMODEL=(profile-name [,GENERIC])
  • STORCLAS=storage-class-name

For more information on SMS attributes, see the IBM Sterling Connect:Direct for z/OS user documentation.
RemoteSPACE Specifies the amount of storage to be allocated for new files on the destination node. If SPACE is specified, the RemoteDISP of the destination file must be NEW or RPL. Optional.

Used only on the z/OS platform. Valid syntax is:

(CYL | TRK | blk,

(prim , [sec] , [dir]), [RLSE] , [CONTIG] , [ROUND]) |

(av-rec-len , (primary-rcds , [secondary-rcds] , [dir])

)

For more information on how to specify SPACE information, see the IBM Sterling Connect:Direct for z/OS documentation.
RemoteUNIT Specifies the storage device or type along with the number of devices required. Optional.

Used only on the z/OS platform. Valid syntax is:

([unit-address | device-type | group-name], [unit-count | P ] [,DEFER])

For more information on how to specify UNIT information, see the IBM Sterling Connect:Direct for z/OS documentation.

Note: Unittype was coded in the old DCB parameter.
RemoteVOL Specifies one or more volume serial numbers containing the destination file and optional processing associated with the file. Optional.

Used only on the z/OS platform. Valid syntax is:

([PRIVATE],[RETAIN]

,[volume-sequence-no] ,[volume-count]

[,SER=(serial-no [,serial-no,...])

|SER=serial-no)

|([SER=(serial-no ,[serial-no,...]))

|(REF=dsn])

For more information on how to specify VOL information, see the IBM Sterling Connect:Direct for z/OS documentation.

Note: Volumecount was coded in the old DCB parameter.
SessionToken Identifies an established session between two Sterling Connect:Direct nodes. Required.

Valid value is an XML structure that includes the following elements:

  • SessionId
  • ProcessNumber
  • ProcessName
  • SubmitDateTime
  • RemoteCDNodeName
  • RemoteUserId
  • RemotePasswd
  • PlexClass
  • MaxRestartRetries
  • RestartRetryInterval
  • ShortTermMaxRetries
  • ShortTermRetryInterval
Sysopts Remote system operations to be implemented on the remote Sterling Connect:Direct node. Optional.

For example (for copying to IBM Sterling Connect:Direct for Microsoft Windows only):

Datatype(text) xlate(yes)

For more information, see your IBM Sterling Connect:Direct documentation.

Parameters Passed from CopyTo Service to Business Process

This table describes the parameters passed from the Sterling Connect:Direct Server CopyTo service to the business process:

Parameter Description
LocalCDNodeName Local Sterling Connect:Direct server instance name. Required.
RemoteCDNodeName Remote Sterling Connect:Direct server instance name. Required.
BytesSent Number of bytes sent as part of Copy operation. Required.

Valid value is a positive integer.
Status Indicates the status of the Copy operation. Required. Valid values are SUCCESS and ERROR.
CopyStartDateTime Indicates Copy operation begin date and time. Required. Valid value is in the format: YYYY MM DD hhmm.
CopyEndDateTime Indicates Copy operation end date and time. Required. Valid value is in the format: YYYY MM DD hhmm.

Sterling Connect:Direct Server CopyTo Business Process Example

This example illustrates using the Sterling Connect:Direct Server CopyTo service in a business process. The business process copies the current primary document to the remote Sterling Connect:Direct server, which is identified with a session token. 

<process name=" CopyToExample">
  <sequence name="CDServerCopyToGIS">
    <!-- Begin Server Session -->
        <operation name="Sterling Connect:Direct Server Begin Session Service">
          <participant name="CDServerBeginSession"/>
          <output message="CDServerBeginSessionServiceTypeInputMessage">
            <assign to="." from="*"></assign>
            <assign to="LocalCDNodeName">TEST1_CDSERVER</assign>
            <assign to="RemoteCDNodeName">REMOTECDNODE1</assign>
            <assign to="RemoteUserId">user1</assign>
            <assign to="RemotePasswd">password1</assign>
          </output>
          <input message="inmsg">
            <assign to="BeginSessionResults" from="*"></assign>
          </input>
        </operation>
        <operation name="Sterling Connect:Direct Server Copy To Service">
          <participant name="CDServerCopyTo"/>
          <output message="CDServerCopyToServiceTypeInputMessage">
            <assign to="." from="*"></assign>
            <assign to="SessionToken"
                    from="//BeginSessionResults/SessionToken/node()"></assign>
            <assign to="RemoteFileName">sample.txt</assign>
            <assign to="BinaryMode">no</assign>
            <assign to="Sysopts"> datatype(text) xlate(no)</assign>
          </output>
          <input message="inmsg">
            <assign to="CopyToResults" from="*"></assign>
          </input>
        </operation>
    <!-- End Server Session -->
        <operation name="Sterling Connect:Direct Server End Session Service">
          <participant name="CDServerEndSession"/>
          <output message="CDServerEndSessionServiceTypeInputMessage">
            <assign to="." from="*"></assign>
            <assign to="SessionToken"
                    from="//BeginSessionResults/SessionToken/node()"></assign>
          </output>
          <input message="inmsg">
            <assign to="EndSessionResults" from="*"></assign>
          </input>
        </operation>
  </sequence>
</process>