Routing control statements

You code two types of control statements in the routing-control data set:

One TCP/IP statement

The TCP/IP statement identifies the name of the TCP/IP address space in the z/OS® system.

Multiple routing statements

Each routing statement associates a set of routing criteria with the socket address of a remote target system and server.

Typically, you would define one routing statement for each server; however, if you want to route data sets with varying combinations of criteria to the same server, you can code more than one statement per server.

Figure 1 summarizes the parameters of a routing statement.

The parameters of the routing statement are:

ALTFILENAME={NONE | GROUPNAME | AFPDP}

Specifies whether Download for z/OS sends an alternative file name to the remote file system.

NONE

Do not send an alternative file name.

GROUPNAME

Substitute the Output Group Name for the Data Set Step Name as the third qualifier in the file name.

AFPDP

Use the AFP Download Plus file name in place of the Download for z/OS file name.

This parameter is optional. If you omit it, the default is NONE.

Example:

    ALTFILENAME=NONE                   
  

CLASS=classes

Specifies up to eight class values. Each class is one-alphanumeric character. Do not separate the class values by commas. Download for z/OS compares each value that is specified to the value on the CLASS parameter of the DD or OUTPUT JCL statement.

This parameter is optional; however, if you do not specify CLASS, you must specify either DEST or FORMS, or both. If you omit CLASS, Download for z/OS ignores the output class that is specified on the DD or OUTPUT JCL statement.

Example:

CLASS=QR

DEST=destination _names

Specifies up to eight destination names, which are separated by commas. Each destination name is 1 - 8 characters. Download for z/OS compares each value that is specified to the value on the DEST parameter of the DD or OUTPUT JCL statement.

This parameter is optional; however, if you do not specify DEST, you must specify either CLASS or FORMS, or both. If you omit DEST, Download for z/OS ignores the destination that is specified on the DD or OUTPUT JCL statement.

Example:

DEST=AIX1,AIX2

FORMS=form_names

Specifies up to eight form names, which are separated by commas. Each form name is 1 - 8 alphanumeric characters. Download for z/OS compares each value that is specified to the value on the FORMS parameter of the DD or OUTPUT JCL statement.

This parameter is optional; however, if you do not specify FORMS, you must specify either CLASS or DEST, or both. If you omit FORMS, Download for z/OS ignores the form name that is specified on the DD or OUTPUT JCL statements.

Example:

FORMS=BILLS,RECEIPTS

IPADDR=host_address

Specifies the address of the remote system. Specify one of these:

• Host name with these restrictions:
  • The name can be a maximum of 72 characters long.
  • These characters are not allowed: , / = ? ;
• Dotted decimal address in the format nnn.nnn.nnn.nnn
• Colon hexadecimal address in the format

  X'nnnn':X'nnnn':X'nnnn':X'nnnn':X'nnnn':X'nnnn':X'nnnn':X'nnnn'

  with these restrictions:
  • Leading zeros in each hexadecimal value can be omitted. For example: 2001:db8:85a3:0:0:8a2e:c22:384e
  • One sequence of repeat zero values can be omitted. For example: 2001:db8:85a3::8a2e:c22:384e
  • The last two hexadecimal digits can be in dotted decimal notation. For example: 2001:db8:85a3::8a2e:12.34.56.78

This parameter is required.

Examples:

IPADDR=denver.mysystem

IPADDR=20.97.8.201

IPADDR=69DC:8864:FFFF:FFFF:0C22:1280:8C0A:FFFF

LOGJOBS={YES | NO}

Specifies whether a message is logged for jobs that are successfully sent to the receiving server or canceled by the operator. When YES is specified, message APS988I is logged in the SYSLOG data set for each job that is successfully sent or message APS993I is logged for each canceled job.

This parameter is optional. If you omit it, the default is NO.

Example:

LOGJOBS=YES

PORTNUM=port_number

Specifies the port number of the target server. This port number must not be used by other applications in the target system and must match the port number that is specified on the command that is used to start the server. The valid range of port numbers is: 5002 - 64000, except 8251 and 8253, which are not allowed. Avoid 6874 - 6889 and 15080, which print servers might use for other purposes.

This parameter is required.

Example:

PORTNUM=6001

RETRYINTV={retry_interval | 10}

Specifies the number of seconds before the transmission is tried again. Specify a number 0 - 99999. The retry interval is the amount of time Download for z/OS waits after it issues an error message (such as APS989I) before it tries to reestablish the TCP/IP connection. The retry interval is in addition to any TCP/IP timeout or retries that are done before the error message is issued.

This parameter is optional. If you omit it, the default is 10, meaning that Download for z/OS tries the transmission again after 10 seconds pass.

Notes:

1. IBM® suggests that you do not specify a long retry interval because Download for z/OS does not process another data set until all retries are attempted.
2. The retry interval can be 30 seconds longer than expected when you use IBM TCP/IP and the CONNECT command fails.

Example:

RETRYINTV=60

RETRYNUM={number_of_retries | 1}

Specifies the maximum number of times Download for z/OS is to try a failed transmission again. Specify a number 0 - 999. If, after the specified number of retries, the transmission is still unsuccessful, Download for z/OS releases the data set to JES to be held by the z/OS system. Download for z/OS issues an error message for each transmission attempt that fails, including the original attempt and each retry failure. Any retries that are done by TCP/IP are not counted.

This parameter is optional. If you omit it, the default is 1, meaning that Download for z/OS tries a failed transmission again one time.

Note: IBM suggests that you do not specify numerous retries because Download for z/OS does not process another data set until all retries are attempted.

Example:

RETRYNUM=3

SEND_REC_LENGTH={YES | NO}

Specifies whether each record is to be prefixed with a length field.

Specify YES if the target server is a print server. Specify NO only if MO:DCA-P documents are being transmitted to an OnDemand server because MO:DCA-P records already contain a record length. The AFP Conversion and Indexing Facility (ACIF), for example, creates MO:DCA-P documents. Specifying NO might improve performance for OnDemand applications.

This parameter is optional. If you omit it, the default is YES.

Example:

SEND_REC_LENGTH=NO

TRACE_USER_DATA={YES | NO}

Specifies whether user data is traced when a trace function is requested with PSF. User data is traced when YES is specified and user data is available. For more information about using traces, see PSF for z/OS: Diagnosis.

This parameter is optional. If you omit it, the default is YES.

Example:

TRACE_USER_DATA=YES

YEAR_FORMAT=YY | YYYY

Specifies the format of the year portion of the file name that Download for z/OS generates. The generated file name has this general format:

MVS_system.jobname[.step_name].form_name.yyddd.hhmmsstuvwx

or

MVS_system.jobname[.step_name].form_name.yyyyddd.hhmmsstuvwx

See Locating transmitted files on remote file systems for a complete description of the file name format.

If you specify YY, the year is represented as 2 digits, such as 99 or 01. If you specify YYYY, the year is represented as 4 digits, such as 1999 or 2001.

This parameter is optional. If you omit it, the default is YYYY, which represents the year as 4 digits.

The YEAR_FORMAT keyword setting applies to all new data sets that Download for z/OS transmits. Any data set that was partially transmitted and checkpointed is retransmitted by using the original file name. The current setting of YEAR_FORMAT does not affect the file name for these data sets.

If you specify more than one of the three routing parameters (that is, CLASS, DEST, or FORM) on one routing statement, data sets must match all of the specified parameters to be routed to the associated server.