Content of CLIENT data set

The CLIENT data set contains information about the environment of the local system, such as how to navigate an FTP firewall and an HTTP proxy server. See Syntax rules for XML statements for a description of the general syntax rules that apply to this data set.


CLIENT tag

>>-<CLIENT--+-------------------+--+-----------+---------------->
            '-debug="-+-YES-+-"-'  '-retry="n"-'   
                      '-NO--'                      

>--+--------------------+--+-----------------+------------------>
   '-ftpccc="-+-YES-+-"-'  '-javahome="path"-'   
              '-NO--'                            

>--+------------------+--+----------------------------+--------->
   '-classpath="path"-'  '-javadebugoptions="options"-'   

>--+------------------------------+----------------------------->
   '-downloadmethod="-+-ftp---+-"-'   
                      +-http--+       
                      '-https-'       

>--+----------------------------------------+-->---------------->
   '-downloadkeyring="-+-keyring_name---+-"-'      
                       '-javatruststore-'          

>--<FTPOPTIONS>--ftp parameters--</FTPOPTIONS>------------------>

>--+--------------------------+--------------------------------->
   '-| FTP firewall options |-'   

>--+------------------------------+--</CLIENT>-----------------><
   +-| HTTP proxy options |-------+              
   '-| HTTP SOCKS proxy options |-'


FTP firewall options

>>-<FIREWALL>--| SERVER options |------------------------------->

   .---------------------------------.                
   V                                 |                
>----<FIRECMD>--commands--</FIRECMD>-+--</FIREWALL>------------><


SERVER options

>>-<SERVER--host="-+-host name--+-"----------------------------->
                   '-ip address-'     

>--+-------------------------------+--+--------------------+---->
   '-account="account information"-'  '-port="port number"-'   

>--+---------------+--+---------------+-->--</SERVER>----------><
   '-user="userid"-'  '-pw="password"-'


HTTP proxy options

>>-<HTTPPROXY--host="-+-host name--+-"-------------------------->
                      '-ip address-'     

>--+--------------------+--+------------------------------+----->
   '-port="port number"-'  '-user="userid"--pw="password"-'   

>-->--</HTTPPROXY>---------------------------------------------><


HTTP SOCKS proxy options

>>-<HTTPSOCKSPROXY--host="-+-host name--+-"--------------------->
                           '-ip address-'     

>--+--------------------+--+------------------------------+----->
   '-port="port number"-'  '-user="userid"--pw="password"-'   

>-->--</HTTPSOCKSPROXY>----------------------------------------><

<CLIENT>

specifies the start of the local environment data. This tag is required.

The attributes for the <CLIENT> tag are:

debug

specifies whether SMP/E should invoke the z/OS® FTP client using the -d parameter to generate tracing output. A value of YES indicates that tracing output should be generated. A value of NO is equivalent to not specifying the debug attribute and indicates that tracing output should not be generated. The attribute value must be enclosed in quotation marks. The value may be entered in mixed case, but is folded to uppercase for verification. The debug attribute is optional.

retry

One numeric character (0-9) indicating the number of times to retry the transfer of a file when its SHA-1 hash value does not match the hash value expected for this file. This tag is optional. If the retry attribute is not specified, no retries will be attempted. This attribute must be enclosed in quotation marks.

ftpccc

specifies whether SMP/E should use the z/OS FTP client CCC subcommand. The CCC subcommand (Clear Command Channel) changes the FTP control connection from encrypted mode to clear text mode.

A value of YES is the default if ftpccc is not specified. It indicates that after the FTP client connects to the server, negotiates a secure and encrypted connection, and authenticates using user and password, SMP/E will send the CCC subcommand to change the control connection from encrypted to clear text. Subsequent clear text commands and responses on the FTP control connection can often help solve data connection problems for encrypted connections behind a Network Address Translation (NAT) firewall router.

A value of NO indicates a secure and encrypted control connection will not be changed to clear text. A value of NO is sometimes required when a firewall prohibits changing an encrypted FTP control connection to clear text.

The ftpccc attribute value must be enclosed in quotation marks. Also the value may be entered in mixed case, but is folded to uppercase for verification.

The ftpccc attribute is optional and its value is ignored if the FTP control connection is not encrypted.

javahome

specifies the path used to locate the Java™ runtime. SMP/E requires the Java runtime for several operations, including RECEIVE ORDER processing, downloading GIMZIP packages using HTTP or HTTPS, and to calculate SHA-1 hash values for RECEIVE FROMNETWORK when ICSF is not active. If the Java runtime is not specified using an SMPJHOME DD statement or DDDEF entry, then the directory can be specified on the javahome attribute. For example, javahome="/usr/lpp/java/J7.0". If a javahome value is specified, it must be a valid directory. A valid directory is from 1 to 255 characters in length, and must include only characters X'40' through X'FE' excluding the reserved XML characters, less than (<), greater than (>), double quotation mark (") and ampersand (&).

Note: The javahome directory can also be specified using the SMPJHOME DD statement or DDDEF entry. When specified, these values override the javahome attribute value from the client data set. For more information about setting the javahome directory, see the topic on "Preparing to use RECEIVE ORDER processing" in SMP/E for z/OS User's Guide.

classpath

specifies the search path for the SMP/E Java application classes. If the classpath is not specified using an SMPCPATH DD statement or DDDEF entry, then the directory may be specified on the classpath attribute. For example, classpath="/usr/lpp/smp/classes/". If classpath is not specified either in the client data set or by using an SMPCPATH DD statement or DDDEF entry, a default classpath value of "/usr/lpp/smp/classes/" is used. If a classpath value is specified, it must be a valid directory. A valid directory is from 1 to 255 characters in length, and must include only characters X'40' through X'FE' excluding the reserved XML characters, less than (<), greater than (>), double quotation mark (") and ampersand (&).

Note: The classpath directory can also be specified using the SMPCPATH DD statement or DDDEF entry. When specified, these values override the classpath attribute value from the client data set. For more information about setting the classpath directory, see the topic on "Preparing to use RECEIVE ORDER processing" in SMP/E for z/OS User's Guide.

javadebugoptions

specifies a character string, provided to you by IBM®, to indicate what debug and trace information should be produced when invoking the SMP/E java application classes. The debug and trace information is written to the print file for the HFSCOPY utility (SYSPRINT is SMP/E's default print file, and is used if no PRINT subentry was specified in the active UTILITY entry for the HFSCOPY utility).

If a debug options value is specified, it must be from 1 to 300 characters in length, and include only characters X'40' through X'FE' excluding the reserved XML characters, less than (<), greater than (>), double quotation mark (") and ampersand (&).

Typical debug options that may be specified are as follows:

-showversion: to indicate the version information for the level of Java being used.
-Dcom.ibm.smp.debug=severe: provides detailed debug and trace information for the SMP/E java classes.
-Djava.security.debug: provides detailed debug information regarding java access control processing.
-Djavax.net.debug: provides detailed debug information for the phases of SSL/TLS processing.

downloadmethod

Identifies the network protocol to use for downloading the package files from the server to the local z/OS system, and may be a value of ftp, http, or https. If downloadmethod is not specified, the default is ftp. If https is specified, then certificates are required to perform the SSL handshake with the HTTPS server and thus to encrypt the network activity. The location of the necessary certificates is defined on the downloadkeyring attribute. End of change

downloadkeyring

Identifies the location of the certificates required to perform SSL operations with the HTTPS server where the files to be downloaded reside. The name for a security manager keyring or the keyword javatruststore may be specified.

keyring-name

Identifies the name for a security manager keyring that contains the certificates required to perform SSL operations with the HTTPS server. The specified name may be for a real or virtual keyring. Keyring names are from 1 to 237 characters in length and may include only characters X'40' through X'FE' excluding the forward slash (/) and the reserved XML characters, less than (<), greater than (>), double quotation mark ("), and ampersand (&).

If the keyring is associated with a userid other than that used to execute SMP/E, then the keyring name must be prefixed with the associated userid. Userids are from 1 to 8 alphanumeric characters in length, can consist entirely of numerics and need not begin with any particular character. The userid is separated from the keyring value by a forward slash (userid/keyring).

To indicate all of the Certificate Authority (CA) certificates defined in the security manager may be used to perform SSL operations, use the CERTAUTH virtual keyring by specifying the userid/keyring value “*AUTH*/*”.

Note: The userid under which SMP/E runs must be properly authorized to the FACILITY class resource IRR.DIGTCERT.LISTRING for SMP/E to use the specified keyring. READ access is required for a userid to use its own keyring or the CERTAUTH virtual keyring. UPDATE access is required to use a keyring from another user.

javatruststore

Indicates all of the certificates in the default Java truststore may be used to perform the SSL handshake. A Java truststore is a Java keystore file containing the collection of trusted Certificate Authority (CA) certificates. The default Java truststore is located relative to the Java home directory, which is specified on the javahome attribute in the <CLIENT> tag, or on the SMPJHOME DD statement.

For the RECEIVE FROMNETWORK command and the GIMGTPKG service routine, if downloadmethod=https, then downloadkeyring is required. For the RECEIVE ORDER command, if downloadmethod=https, then the keyring can be identified either with the downloadkeyring attribute, or the keyring attribute in the ORDERSERVER data set. End of change

<FTPOPTIONS>

specifies the start of the FTP parameters section of the CLIENT data set. The <FTPOPTIONS> section can be specified only once.

ftp parameters

identifies the z/OS FTP Client parameters that are to be specified when SMP/E invokes the z/OS FTP Client program to transfer a package. SMP/E runs the FTP program in the z/OS UNIX environment, therefore the ftp parameters must be supplied in the standard UNIX flag format (for example, -d). See z/OS Communications Server: IP User’s Guide and Commands for information about the FTP Client parameters.

If ftp parameters are specified, their value must be 1 to 300 characters in length, and include characters X'40' through X'FE' only, excluding the reserved XML characters, less than (<), greater than (>), and ampersand (&). SMP/E does not validate the specified parameters before passing them to the FTP Client program.

Note:

You do not need to specify the -e and -d FTP parameters in the <FTPOPTIONS> element. SMP/E automatically includes the -e parameter. Also, if the debug="yes" attribute is specified in the CLIENT tag, SMP/E includes the -d parameter, when invoking the FTP Client program.
Do not specify the host name or port number in the ftp parameters.

</FTPOPTIONS>

specifies the end of the FTP parameters section. This tag is required if <FTPOPTIONS> was specified.

<FIREWALL>

specifies the start of the firewall section of the local FTP client environment data.

The firewall section of the CLIENT data set should be specified if your TCP/IP environment requires that you connect to the firewall machine to execute FTP commands.

Following the <FIREWALL> tag are:

<SERVER>

specifies the start of the server information of the firewall section of the FTP client environment data. This tag is required if <FIREWALL> was specified.

The <SERVER> section of the <FIREWALL> entry contains the information that SMP/E needs to connect to the firewall host.

The attributes for the <SERVER> tag are:

host

identifies the firewall host. The host attribute must specify either:

host name: a fully qualified internet name for the firewall host that can be resolved by the domain name system to an internet address. A host name is a text string up to 255 characters drawn from the alphabet (A-Z), digits (0-9), period (.), and minus sign (-). Periods are allowed only as delimiters within domain style names. No blank or space characters are permitted as part of a name. No distinction is made between upper and lower case. The first character must be a letter or a digit. The last character must not be a minus sign or period.
host ip address: an internet address defining the firewall host's location on the internet. An internet address can be an IPv4 or IPv6 address. An IP address can be up to 255 nonblank characters excluding the reserved XML characters, < (X'4C'), > (X'6E'), double quotation mark (X'7F') and ampersand (X'50').

One host attribute specifying either a host name or a host IP address is required. The host attribute value must be enclosed in quotation marks

user

id that will give you access to the firewall host machine. This attribute must be enclosed in quotation marks.

pw

specifies a password value that will give you access to this firewall host. This attribute must be enclosed in quotation marks.

Note: Users should use existing system facilities to restrict access to the data set named on the CLIENT operand to ensure the security of the password value.

account

specifies the account information to be used for the specified user ID. This attribute must be enclosed in quotation marks. This field is a text string up to 80 characters of any type. The account attribute is optional.

port

specifies the port number to be used for TCP/IP operations on the specified host. The port number must be a decimal number in the range 1 through 65535. This attribute value must be enclosed in quotation marks. The port attribute is optional.

</SERVER>

specifies the end of server section of the FTP client environment data. This tag is required if <SERVER> was specified.

<FIRECMD>

specifies the start of the firewall specific command section of the FTP client environment data. This tag is required if the <FIREWALL> tag is specified.

firewall specific commands

Enter the sequence of commands necessary to FTP to an outside host through your firewall. Each command must be on a separate line in the data set. Each command is a text string of up to 80 characters of any type.

SMP/E allows the following substitution variables within the commands in the <FIRECMD> section. Each substitution variable begins with the "&" character and ends with a semi-colon.

&ACCOUNT;: When &ACCOUNT; is encountered within lines in the <FIRECMD> section of the CLIENT data set, the value specified in the account attribute of the <SERVER> section in the <FIREWALL> section is substituted into the command string. If the account attribute is omitted, blanks will be substituted.
&PORT;: When &PORT; is encountered within lines in the <FIRECMD> section of the CLIENT data set, the value specified in the port attribute of the <SERVER> section in the <FIREWALL> section in this CLIENT data set, is substituted into the command string. If no port attribute was specified, a blank will be substituted.
&PW;: When &PW; is encountered within lines in the <FIRECMD> section of the CLIENT data set, the value specified in the pw attribute of the <SERVER> section in the <FIREWALL> section of this CLIENT data set is substituted into the command string. If the pw attribute is omitted, blanks will be substituted.
&REMOTE_ACCOUNT;: When &REMOTE_ACCOUNT; is encountered within lines in the <FIRECMD> section of the CLIENT data set, the value substituted into the command string depends on the form of the RECEIVE command being executed. For RECEIVE FROMNETWORK, the value specified in the account attribute entry of the <SERVER> section in the data set identified by the SERVER DD is substituted into the command string. If the account attribute is omitted, blanks will be substituted. For RECEIVE ORDER, the proper value is provided automatically by the IBM order server.
&REMOTE_HOST;: When &REMOTE_HOST; is encountered within lines in the <FIRECMD> section of the CLIENT data set, the value substituted into the command string depends on the form of the RECEIVE command being executed. For RECEIVE FROMNETWORK, the value specified in the host attribute of the <SERVER> section in the SERVER data set is substituted into the command string. For RECEIVE ORDER, the proper value is provided automatically by the IBM order server.
&REMOTE_PORT;: When &REMOTE_PORT; is encountered within lines in the <FIRECMD> section of the CLIENT data set, the value substituted into the command string depends on the form of the RECEIVE command being executed. For RECEIVE FROMNETWORK, the value specified in the port attribute of the <SERVER> section in the SERVER data set is substituted into the command string. If no port attribute was specified, a blank will be substituted. For RECEIVE ORDER, the proper value is provided automatically by the IBM order server.
&REMOTE_PW;: When &REMOTE_PW; is encountered within lines in the <FIRECMD> section of the CLIENT data set, the value substituted into the command string depends on the form of the RECEIVE command being executed. For RECEIVE FROMNETWORK, the value specified in the pw attribute of the <SERVER> section in the data set identified by the SERVER DD is substituted into the command string. If the pw attribute is omitted, blanks will be substituted. For RECEIVE ORDER, the proper value is provided automatically by the IBM order server.
&REMOTE_USER;: When &REMOTE_USER; is encountered within lines in the <FIRECMD> section of the CLIENT data set, the value substituted into the command string depends on the form of the RECEIVE command being executed. For RECEIVE FROMNETWORK, the value specified in the user attribute of the <SERVER> section in the data set identified by the SERVER DD is substituted into the command string. If the user attribute is omitted, blanks will be substituted. For RECEIVE ORDER, the proper value is provided automatically by the IBM order server.
&USER;: When &USER; is encountered within lines in the <FIRECMD> section of the CLIENT data set, the value specified in the user attribute of the <SERVER> section in the <FIREWALL> section in this CLIENT data set, is substituted into the command string. If the user attribute is omitted, blanks will be substituted

</FIRECMD>

specifies the end of the firewall specific command section of the FTP client environment data. This tag is required if <FIRECMD> was specified.

</FIREWALL>

specifies the end of firewall section of the FTP client environment data. This tag is required if <FIREWALL> was specified.

<HTTPPROXY>

specifies the start of the HTTP proxy section of the CLIENT data set. Start of change

Data should be specified only if your network environment requires that you use a proxy server to perform HTTP communications with a remote server. End of change

host

identifies the proxy server used for HTTP communications. This attribute value must be either:

hostname: a fully qualified internet host name that can be resolved by the domain name system to an internet address. Host name values are from 1 to 255 characters, from the set of mixed case alphanumeric, period (.), and minus sign (-). The first and last character must be alphanumeric.
ip address: an internet address defining the host's location on the internet. The internet address can be an IPv4 or IPv6 address. An IP address can be from 1 to 255 nonblank characters excluding the reserved XML characters, less than (<), greater than (>), double quotation mark (") and ampersand (&).

port

specifies the port number to be used for TCP/IP operations with the specified proxy server. The port number must be a decimal number in the range 1 through 65535. The port value is optional, and SMP/E's default value is 80.

user

specifies a user ID that will allow access to the proxy server. User ID values can be from 1 to 80 characters excluding the reserved XML characters, less than (<), greater than (>), double quotation mark (") and ampersand (&).

pw

specifies a password value that will allow access to the proxy server. Password values can be from 1 to 80 characters excluding the reserved XML characters, less than (<), greater than (>), double quotation mark (") and ampersand (&).

</HTTPPROXY>

specifies the end of the HTTP proxy data.

<HTTPSOCKSPROXY>

specifies the start of the HTTP SOCKS proxy section of the CLIENT data set. Start of change

Data should be specified only if your network environment requires that you use a SOCKS proxy server to perform HTTP communications with a remote server. End of change

host

identifies the SOCKS proxy server used for HTTP communications. This attribute value must be either:

hostname: a fully qualified internet host name that can be resolved by the domain name system to an internet address. Host name values are from 1 to 255 characters, from the set of mixed case alphanumeric, period (.), and minus sign (-). The first and last character must be alphanumeric.
ip address: an internet address defining the host's location on the internet. The internet address can be an IPv4 or IPv6 address. An IP address can be from 1 to 255 nonblank characters excluding the reserved XML characters, less than (<), greater than (>), double quotation mark (") and ampersand (&).

port

specifies the port number to be used for TCP/IP operations with the specified SOCKS proxy server. The port number must be a decimal number in the range 1 through 65535. The port value is optional, and SMP/E's default value is 1080.

user

specifies a userid that will allow access to the SOCKS proxy server. User ID values can be from 1 to 80 characters excluding the reserved XML characters, less than (<), greater than (>), double quotation mark (") and ampersand (&).

pw

specifies a password value that will allow access to the SOCKS proxy server. Password values can be from 1 to 80 characters excluding the reserved XML characters, less than (<), greater than (>), double quotation mark (") and ampersand (&).

</HTTPSOCKSPROXY>

specifies the end of the HTTP SOCKS proxy data.

</CLIENT>

specifies the end of local client environment data. This tag is required.