MODIFY command: FTP

Use the MODIFY command to start and stop tracing after initialization is complete. The MODIFY command for z/OS® FTP has two keywords: one for general tracing (DEBug) and one for extended tracing (DUMP).

Only FTP sessions established after trace is active can be traced. When tracing is stopped, sessions currently connected to the server will continue to be traced; new FTP sessions will not be traced.

Format


>>-+-MODIFY-+--jobname--,--------------------------------------->
   '-F------'               

                  .-------------------.     
                  V                   |     
>--+-DEBug--=--(----+------------+--,-+-+----------------------->
   |                +-?----------+      |   
   |                +-ACC--------+      |   
   |                +-ALL--------+      |   
   |                +-BAS--------+      |   
   |                +-CMD--------+      |   
   |                +-FLO--------+      |   
   |                +-FSC--(n)---+      |   
   |                +-INT--------+      |   
   |                +-JES--------+      |   
   |                +-NONE-------+      |   
   |                +-PAR--------+      |   
   |                +-SEC--------+      |   
   |                +-SOC--(n)---+      |   
   |                +-SQL--------+      |   
   |                +-UTL--------+      |   
   |                |        (1) |      |   
   |                '-X--yyy-----'      |   
   |             .-------------------.  |   
   |             V                   |  |   
   '-DUmp--=--(----+------------+--,-+--'   
                   +-?----------+           
                   +-n----------+           
                   +-ALL--------+           
                   +-FSC--------+           
                   +-JES--------+           
                   +-NONE-------+           
                   +-SOC--------+           
                   +-SQL--------+           
                   |        (1) |           
                   '-X--yyy-----'           

>--+---------------------------+--)----------------------------><
   +-USERID--(--filter_name--)-+      
   '-IPADDR--(--filter--)------'

Notes:

Prepend any option yyy with X to turn off that trace.

Parameters

DEBug

Subcommand to begin general tracing. General tracing includes the following options:

?

Displays the status of the general traces.

Note: The status of the trace is displayed as a response to all uses of the MODIFY DEBug command. The ? allows you to obtain the status without making a change.

ACC

Displays the details of the login process.

ALL

Sets all of the trace points.

Note: Both the FSC and the SOC trace are set to level 1 when the ALL parameter is processed.

BAS

Sets a select group of traces that offer the best overall details without the intense tracing of some of the traces. This is equivalent to:

MODIFY jobname,DEBUG=(CMD,INT,FSC,SOC)

CMD

Shows each command and the parsing of the parameters for the command.

FLO

Shows the flow of control within FTP. It is useful to show which services of FTP are used for an FTP request.

FSC(n)

Shows details of the processing of the file services commands APPE, STOR, STOU, RETR, DELE, RNFR, and RNTO. This trace can be very intense and therefore it allows you to specify levels of granularity for the trace points. The level 1 tracing that is specified by entering FSC or FSC(1) is the level that is normally used unless more data is requested by TCP/IP service group. The variable n can be a number in the range 1 – 8.

INT

Shows the details of the initialization and termination of the FTP session.

JES

Shows details of the processing for JES requests, such as when SITE FILETYPE=JES is in effect.

NONE

Turn off all of the traces.

PAR

Shows details of the FTP command parser. It is useful for debugging problems in the handling of the command parameters.

SEC

The SEC trace shows the processing of security functions such as TLS and GSSAPI negotiations.

SOC(n)

Shows details of the processing during the setup of the interface between the FTP application and the network as well as details of the actual amounts of data that is processed. This trace can be very intense and therefore it allows you to specify levels of granularity for the trace points. The level 1 tracing that is specified by entering SOC or SOC(1) is the level normally used unless more data is requested by the TCP/IP service group. The variable n can be a number in the range 1 – 8.

SQL

Shows details of the processing for SQL requests, such as when SITE FILETYPE=SQL is in effect.

UTL

Shows the processing of utility functions such as CD and SITE.

Xyyy

Turns off an active option, where yyy is the option. For example: XUTL turns off the UTL option.

DUMp

Subcommand to begin extended tracing. Extended tracing includes the following options:

?: Displays the status of the extended traces.
n: Specifies the number of a specific extended trace point that is to be activated in the FTP code. The number has a range of 1 – 99.
ALL: Activates all of the trace points.
FSC: Activates all of the extended trace points in the file services code. The numbers activated are 20 – 49.
JES: Activates all of the extended trace points in the JES services code. The numbers activated are 60–69.
NONE: Turns off all extended traces.
SOC: Activates all of the extended trace points in the network services code. The numbers activated are 50–59.
SQL: Activates all of the extended trace points in the SQL services code. The numbers activated are 70–79.
Xyyy: Turns off an active option, where yyy is the option. For example: XUTL turns off the UTL option.

USERID(filter_name)

Filter the trace for user IDs matching the filter_name pattern.

If the user ID matches the filter at the time the client logs in, then tracing options are set to the current value of the options. Otherwise, there are no tracing options set. The client might use the SITE command to set options after login if the initial ones are not appropriate. An example for the USERID filter is MODIFY jobname,DUMP=(21,USERID(USER33)) which activates the dumpID 21 trace for a user if the user ID is USER33.

IPADDR(filter)

Filter the trace for IP addresses matching the filter pattern.

If the IP address matches the filter at the time the client connects, then tracing options will be set to the current value of the options. Otherwise, no tracing options will be set. The client might use the SITE command to set options after connect if the initial ones are not appropriate. An example of the IPADDR filter is MODIFY jobname,DEBUG=(JES,IPADDR(9.67.113.57)) which will activate the JES trace for a client whose IP address is 9.67.113.57. Specify the filter address in dotted decimal format if the IP address is an IPv4 address. Indicate submasking by using a slash followed by a dotted decimal submask. For example, 192.48.32/255.255.255.0 will allow addresses from 192.48.32.00 to 192.48.32.255.

Specify the filter address for an IPv6 address as x:x:x:x:x:x:x:x, where the xs are the hexadecimal values of the eight 16-bit pieces of the address. Alternate notations described in RFC 2373 (IP Version 6 Addressing Architecture) are acceptable.

For example,

MODIFY jobname,DEBUG=(JES,IPADDR(FEDC:BA98:7654:3210:FEDC:BA98:7654:3210)
MODIFY jobname,DUMP=(FSC,IPADDR(::1))

Indicate IPv6 network prefixing using a slash followed by the number of prefix bits. For example, use 12AB:0:0:CD30::/60 to indicate the prefix 12AB00000000CD3 (hexadecimal).

MODIFY JOBNAME,DEBUG=(JES,IPADDR(12AB:0:0:CD30::/60))

Usage

The specification of the trace on the MODIFY command is not additive. That is, the trace setting will be that of the last MODIFY command as shown in the following examples.

Using DEBug:

  MODIFY FTPDJG1,DEBUG=(NONE)
  +EZYFT82I Active traces: NONE
  MODIFY FTPDJG1,DEBUG=(CMD)
  +EZYFT82I Active traces: CMD
  MODIFY FTPDJG1,DEBUG=(FSC,USERID(USER33))
  +EZYFT82I Active traces: FSC(1)
  +EZYFT89I Userid filter: USER33
  MODIFY FTPDJG1,DEBUG=(SOC)
  +EZYFT82I Active traces: SOC(1)

Using DUMP:

  MODIFY FTPDJG1,DUMP=(NONE)     
  +EZYFT83I Active dumpIDs: NONE 
  MODIFY FTPDJG1,DUMP=(21)       
  +EZYFT83I Active dumpIDs: 21   
  MODIFY FTPDJG1,DUMP=(22)       
  +EZYFT83I Active dumpIDs: 22

The DUMP keyword can be used as shown in the following example:

  modify jobname,DUMP=(SQL,SOC)      ;sets all SQL and SOC DUMP ID's

  modify jobname,DUMP=(NONE)         ;resets all DUMP ID's 

  modify jobname,DUMP=(Xnn)          ;resets  DUMP ID nn where nn is 
                                     ;a number between 1 and 99

  modify jobname,DUMP=(XFSC)         ;resets all DUMP ID's 20 to 49 

  modify jobname,DUMP=(XSOC)         ;resets all DUMP ID's 50 to 59 

  modify jobname,DUMP=(XJES)         ;resets all DUMP ID's 60 to 69 

  modify jobname,DUMP=(XSQL)         ;resets all DUMP ID's 70 to 79

  modify jobname,DUMP=(NONE,JES,X61) ;resets all ID's and 
                                     ;then sets all JES DUMP ID's 
                                     ;except number 61

The modify jobname,UTRACE command that was supported in releases prior to z/OS V1R2 is not supported in this release. However, its function can be replaced with the following pair of commands:
```
MODIFY jobname,DEBUG=(ALL,USERID(USER33))
MODIFY jobname,DUMP=(ALL,USERID(USER33))
```
Do not specify the ALL parameter on a routine basis, because it can produce an extensive amount of trace data.
The modify jobname,NOUTRACE command that was supported in releases prior to z/OS V1R2 is not supported in this release. If complete tracing was activated as suggested above, then the tracing can be stopped using the following pair of commands:
```
MODIFY jobname,DEBUG=(NONE)
MODIFY jobname,DUMP=(NONE)
```

Context

For additional information see z/OS Communications Server: IP Diagnosis Guide.