Note on usage
Function: Modify partner properties in the partner list
User group: FT administrator
Alias name: FTMODPTN
Functional description
This command can be used to modify the characteristics of a partner that is already entered in the partner list. When changing the partner address, please note that an openFT partner cannot be changed to an FTP partner or an FTAM partner and vice versa.
You can remove an entered dynamic partner from the partner list by setting all the properties to the default values for free dynamic partners by means of the MODIFY-FT-PARTNER command. The default values are the same as the default values in the ADD-FT-PARTNER command with the exception of the SECURITY-LEVEL operand which must be set to *BY-PARTNER-ATTRIBUTES.
Similarly, you can add a free dynamic partner to the partner list by setting at least one of its attributes to a value other than the default. This is possible if PARTNER does not reference a partner list entry and PARTNER-ADDRESS is not specified.
If a partner name for which there is not yet a partner list entry is specified for PARTNER and PARTNER-ADDRESS is also specified, a new named partner list entry is created. This function is intended for the re-import of exported partner entries. To explicitly create new partner entries, you should use ADD-FT-PARTNER.
Format
MODIFY-FT-PARTNER / FTMODPTN |
PARTNER = *ALL / <text 1..200 with-low> ,STATE = *UNCHANGED / *PARAMETERS(...) *PARAMETERS(...) OUTBOUND = *UNCHANGED / *ACTIVE(...) / *DEACT *ACTIVE(...) AUTOMATIC-DEACT = *NO / *YES ,INBOUND = *UNCHANGED / *ACTIVE / *DEACT ,SECURITY-LEVEL = *UNCHANGED / *STD / *BY-PARTNER-ATTRIBUTES / <integer 1..100> ,PARTNER-ADDRESS = *UNCHANGED / <text 1..200 with-low> ,TRACE = *UNCHANGED / *BY-FT-OPTIONS / *ON / *OFF ,IDENTIFICATION = *UNCHANGED / *STD / <composed-name 1..64> / <c-string 1..64 with-low> ,SESSION-ROUTING-INFO = *UNCHANGED / *NONE / *IDENTIFICATION / <alphanum-name 1..8> ,PARTNER-CHECK = *UNCHANGED / *BY-FT-OPTIONS / *STD / *TRANSPORT-ADDRESS ,AUTH-MANDATORY = *UNCHANGED / *NO / *YES ,PRIORITY= *UNCHANGED / *NORMAL / *LOW / *HIGH ,REQUEST-PROCESSING = *UNCHANGED / *STD / *SERIAL ,RECOVERY-OUTBOUND = *UNCHANGED / *ON / *OFF/ *BY-FT-OPTIONS ,KEY-LENGTH = *PARAMETERS (...) *PARAMETERS(...) RSA-PROPOSED = *UNCHANGED / *BY-FT-OPTIONS / 0 / 768 / 1024 / 2048 / 3072 / 4096 ,RSA-MINIMUM = *UNCHANGED / *BY-FT-OPTIONS / 0 / 768 / 1024 / 2048 / 3072 / 4096 |
Operands
PARTNER =
Specifies the partner system.
PARTNER = *ALL
The specified changes are to be implemented for all partner systems defined in the partner list. This specification is only meaningful in conjunction with the operands STATE, SECURITY-LEVEL, TRACE, PARTNER-CHECK, AUTH-MANDATORY, PRIORITY and REQUEST-PROCESSING.
Particular care is necessary when using PARTNER=*ALL in combination with the SECURITY-LEVEL operand.
PARTNER = <text 1..200 with-low>
Specifies either the name of the partner system from the partner list or the address of the partner system (see section “Specifying partner addresses”).
STATE =
Controls the state of the partner system (activated, deactivated).
STATE = *UNCHANGED
The state is unchanged.
STATE = *PARAMETERS(...)
Specifies the settings for locally submitted file transfer requests (outbound) and for remotely submitted file transfer requests.
OUTBOUND =
Specifies the setting for locally submitted file transfer requests to the partner system.
OUTBOUND = *UNCHANGED
The state of locally submitted FT requests is unchanged.
OUTBOUND = *ACTIVE(...)
Locally submitted file transfer requests to the partner system are processed.
AUTOMATIC-DEACT =
Defines if repeated attempts to establish a connection with this partner system should result in a deactivation of the partner system after multiple attempts.
AUTOMATIC-DEACT = *NO
Unsuccessful attempts to establish a connection with this partner system do not lead to its deactivation.
AUTOMATIC-DEACT = *YES
Repeated unsuccessful attempts to establish a connection with this partner system lead to its deactivation. If locally submitted file transfer requests to the partner system are to be executed again after this, the system must be activated explicitly (with OUTBOUND=*ACTIVE).
OUTBOUND = *DEACT
Locally submitted file transfer requests to the partner system are initially not processed (not started) but are stored in the request queue. They are executed only after the partner system has been activated with OUTBOUND=*ACTIVE.
INBOUND =
Specifies the setting for remotely submitted file transfer requests, i.e. requests which were submitted by this partner system.
INBOUND = *UNCHANGED
The state of locally submitted FT requests is unchanged.
INBOUND = *ACTIVE
Remotely submitted file transfer requests from this partner system are processed.
INBOUND = *DEACT
Remotely submitted synchronous file transfer requests from this partner system are rejected. Remotely submitted asynchronous file transfer requests from this partner system are stored there and cannot be processed until the partner system is activated again with INBOUND=*ACTIVE.
SECURITY-LEVEL =
Assigns a security level to a remote system.
SECURITY-LEVEL = *UNCHANGED
The value is unchanged.
SECURITY-LEVEL = *STD
If you set this operand to *STD, a standard security level is assigned to the remote system. This standard security level is defined using the MODIFY-FT-OPTIONS command. Here you can define a fixed value or make the value attribute-dependent.
SECURITY-LEVEL = *BY-PARTNER-ATTRIBUTES
If you set the operand to *BY-PARTNER-ATTRIBUTES then the security level is defined automatically:
Partners that are authenticated by openFT are assigned the security level 10.
Partners, that are known in BCAM (i.e. they are addressed via their BCAM names), are assigned the security level 90.
All other partners are assigned security level 100.
SECURITY-LEVEL = <integer 1..100>
Must be specified if you want to assign a particular security level to the individual partner system.
PARTNER-ADDRESS =
Address of the partner system.
PARTNER-ADDRESS = *UNCHANGED
The address remains unchanged.
PARTNER-ADDRESS = <text 1..200 with-low>
New address for the partner system. For details on the address format, see section“Specifying partner addresses”.
TRACE =
Trace setting for the partner systems. Trace entries are generated only if the FT trace function is activated by means of an operating parameter (MODIFY-FT-OPTIONS TRACE=*ON).
TRACE = *UNCHANGED
The current trace setting is unchanged.
TRACE = *BY-FT-OPTIONS
The trace settings specified in the MODIFY-FT-OPTIONS command are used.
TRACE = *ON
Activates the trace for this partner system even if tracing is deactivated for this partner type in the global settings (MODIFY-FT-OPTIONS). The request-specific trace settings made in MODIFY-FT-OPTIONS, on the other hand, are taken into account.
TRACE = *OFF
For connections to this partner system, only those trace entries which it is technically impossible to suppress are generated. Trace entries which it is technically impossible to suppress are those which are generated before openFT (BS2000) identifies the partner system
IDENTIFICATION =
The network-wide, unique ID of the openFT instance in the partner system.
IDENTIFICATION = *UNCHANGED
The ID remains unchanged.
IDENTIFICATION = *STD
For openFT and FTADM partners, the partner address or the host name from the partner address is used as the identification. No identification is set for FTP and FTAM partners.
IDENTIFICATION = <composed-name 1..64> / <c-string 1..64 with-low>
The network-wide, unique instance ID of the openFT instance in the partner system. This ID is used for authenticating partner systems as of openFT V8.1. It is set by the FT administrator of the partner system (in BS2000, by using MODIFY-FT-OPTIONS IDENTIFICATION=, in Unix systems or Windows, by using ftmodo -id). The uniqueness of this ID must be based on something other than case-sensitivity. An instance ID may be comprised of alphanumeric characters or special characters. It is advisable to use only the special characters “.”, “-”, “:” or “%”.
The initial character must be alphanumeric or the special character “%”. The “%” character may only be used as an initial character. An alphanumeric character must follow the “.” character. For more details on assigning instance identifications, see section “Instanceidentifications”.
With FTAM partners an Application Entity Title can be specified as an identification in the format n1.n2.n3.n4..mmm. For details, see the section "Addressing via Application Entity Title" in the openFT manual "Concepts and Functions".
The instance identification must not be specified with FTP partners!
SESSION-ROUTING-INFO =
If the partner system is only accessible via a go-between instance, specify here the address information, which the go-between instance will use for re-routing. This is necessary, for example, for partner systems using openFT (z/OS), dependent on TRANSIT connections.
SESSION-ROUTING-INFO = *UNCHANGED
The setting remains unchanged.
SESSION-ROUTING-INFO = *NONE
No routing information is used. The session selector can be specified as part of the partner address.
SESSION-ROUTING-INFO = *IDENTIFICATION
Connections to the partner are re-routed via a gateway that uses the instance identification as the address information.
SESSION-ROUTING-INFO = <alphanum-name 1..8>
PARTNER-CHECK =
Enables the global settings for sender checking to be modified on a partner-specific basis. These settings are only effective for named openFT partners that do not work with authentication (see openFT manual "Concepts and Functions").
This setting has no meaning for FTAM partners, FTP partners and dynamic partner entries.
PARTNER-CHECK = *UNCHANGED
The set value remains unchanged.
PARTNER-CHECK = *BY-FT-OPTIONS
The global settings are valid for the partner.
PARTNER-CHECK = *STD
Disable the expanded sender checking. The transport address of the partner is not checked, even if the expanded sender checking is globally enabled (see the MODIFY-FT-OPTIONS command).
PARTNER-CHECK = *TRANSPORT-ADDRESS
Enables expanded sender checking. The transport address is checked, even if the expanded sender checking is globally disabled (see the MODIFY-FT-OPTIONS command). If the transport address under which the partner is reporting does not correspond to the entry in the partner list, the request is rejected.
AUTH-MANDATORY =
Forces the authentication of a named partner system.
AUTH-MANDATORY = *UNCHANGED
The set value is unchanged.
AUTH-MANDATORY = *NO
Authentication is not forced, i.e. this partner system is not restricted with regard to authentication.
AUTH-MANDATORY = *YES
Authentication is forced, i.e. connections to and from this named partner are only permitted when authentication is provided.
PRIORITY=
This operand allows you to specify the priority of the partner system in respect of processing requests that have the same request priority. This means that the partner priority only applies in the case of requests that have the same request priority, but that are issued to partners with a different partner priority.
PRIORITY = *UNCHANGED
The priority of the partner system with regard to the processing of requests with the same request priority remains unchanged.
PRIORITY = *NORMAL
The partner has normal priority.
PRIORITY = *LOW
The partner has low priority.
PRIORITY = *HIGH
The partner has high priority.
REQUEST-PROCESSING =
You use this option to control whether asynchronous outbound requests to this partner system are always run serially or whether parallel connections are permitted.
REQUEST-PROCESSING = *UNCHANGED
The operating mode to this partner system remains unchanged.
REQUEST-PROCESSING = *STD
Parallel connections to this partner system are permitted.
REQUEST-PROCESSING = *SERIAL
Parallel connections to this partner system are not permitted. If multiple file transfer requests to this partner system are pending, then they are processed serially. A follow-up request is consequently not started until the preceding request has terminated.
RECOVERY-OUTBOUND=
This operand controls the partner-specific restart function (recovery) for asynchronous outbound requests.
RECOVERY-OUTBOUND=*UNCHANGED
The current setting for the recovery of outbound requests remains unchanged.
RECOVERY-OUTBOUND=* ON
The restart function for outbound requests is activated for this partner system. This setting is valid only, if the global restart function of the openFT is activated, too.
RECOVERY-OUTBOUND=* OFF
The restart function for outbound requests is deactivated for this partner system.
RECOVERY-OUTBOUND=* BY-FT-OPTIONS
The global setting for the restart function for outbound requests is valid.
KEY-LENGTH = *PARAMETERS(...)
Configuration of the length of the RSA key and the length of the AES key.
RSA-PROPOSED
Length of the RSA key used for encryption. This key is used only to encrypt the AES key which is agreed on between the partners. openFT uses the AES key to encrypt the request description data and possibly also the file contents.
Default setting following adding partner or export from openFT older than version 12.1C70: *BY-FT-OPTIONS.
RSA-PROPOSED = *BY-FT-OPTIONS
This option specifies, that key value will be taken from global openFT options displayed via "SHOW-FT-OPTIONS" command. Either both of key values (RSA-PROPOSED and RSA-MINIMUM) need to be set to "FTOPT" or none. Combination of one key having global value and second local partner value (0 ... 4096) is not allowed, warning will be issued and keys will be adjusted automatically to "FTOPT" value.
RSA-PROPOSED = 0
Encryption is switched off.
RSA-PROPOSED = 768 / 1024 / 2048 / 3072 / 4096
Length of the RSA key (in bits) that is used for the transfer of the AES key of the session.
RSA-MINIMUM
Minimum length of the RSA key (in bits) accepted by the partner system for the transfer of the AES key for the request initiated by the partner.
Default setting following adding partner or export from openFT older than version 12.1C70: *BY-FT-OPTIONS.
RSA-MINIMUM = *BY-FT-OPTIONS
This option specifies, that key value will be taken from global openFT options displayed via SHOW-FT-OPTIONS command. Either both of key values (RSA-PROPOSED and RSA-MINIMUM) need to be set to "FTOPT" or none. Combination of one key having global value and second local partner value (0 ... 4096) is not allowed, warning will be issued and keys will be adjusted automatically to "FTOPT" value.
RSA-MINIMUM = 0
There is no configuration for the minimum length of the RSA key. Every key length is accepted and even requests without encryption can be processed.
RSA-MINIMUM = 768 / 1024 / 2048 / 3072 / 4096
Keys with this minimum length are accepted only. If the initiator uses a shorter key he gets a counter proposal of the responder of the session. A session without encryption will be denied.
Values from 0 to 4096 take priority over the ones specified in global openFT option visible via SHOW-FT-OPTIONS command.
When only RSA-MINIMUM or RSA-PROPOSAL is specified during addition of partner (without specifying second one), then both parameters will be set to global FTOPT values.
During modification of partner, when both keys are set to global “FTOPT” and user modifies only one key to local value, then warning will be prompted and both key values will be adjusted to value specified by user. Additionally, when both keys are set to one of local values and user modifies only one key to global value, then warning will be prompted and both key values will be adjusted to “FTOPT”.
Command return codes
(SC2) | SC1 | Maincode | Meaning |
198 | 1 | CMD0202 | Invalid parameter value. |
83 | 32 | CMD0221 | Internal error. |
35 | 64 | FTR1035 | Command only permissible for FT administrator. |
43 | 64 | FTR1043 | Partner with same attribute already exists in partner list. |
44 | 64 | FTR1044 | Maximum number of partners exceeded. |
45 | 64 | FTR1045 | Partner name not found in partner list. |
46 | 64 | FTR1046 | Modification of partner protocol type not possible. |
SC1/2 = Subcode 1/2 in decimal notation For additional information, see section “Command return codes”. | |||
Example 1
The SECURITY-LEVEL for the partner system TEST is set to 99:
/MODIFY-FT-PARTNER PARTNER=TEST,SECURITY-LEVEL=99
Example 2
The port number for partner WINDOWS (host name = winhost2) is set to 1100:
/MODIFY-FT-PARTNER PARTNER=WINDOWS,PARTNER-ADDRESS=winhost2:1100