EDIT—edit a data set

The EDIT service provides an interface to the ISPF editor and bypasses the display of the Edit Entry Panel. The EDIT interface allows you to use a customized panel for displaying data (use panel ISREFR01 as a model when creating your panel), and lets you specify the initial macro and the edit profile to be used. You can use EDIT to look at any ISPF library, concatenation of ISPF libraries, or data set that can be allocated by using the LMINIT service. You can use the EDIT service recursively, either through nested dialogs or by entering an EDIT command while editing. z/OS ISPF Edit and Edit Macros contains a complete description of the editor.

When EDIT is operating in recovery mode, an audit trail of your interactions is automatically recorded in an ISPF-controlled data set. Following a system failure, you can use the audit trail to recover the data you were editing.

Note:

Dialogs that invoke the EDIT service may invoke the EDREC service first to start edit recovery, because the EDIT service does not do edit recovery.
The EDIT service might alter the DISPLAY environment. Do not expect the DISPLAY environment that existed before invoking the EDIT service to remain unchanged.
The EDIT service cannot be issued by a PL/I main program that also uses subtasking.
When designing applications that will use the EDIT service, be aware that you cannot run EDIT in a pop-up window.

A dialog using EDIT can place data into the ZEDUSER dialog variable in the shared pool. The data in ZEDUSER is saved in the edit recovery table as an extension variable when the recovery data set is initialized. This is done if RECOVERY is ON when first entering Edit or after using the SAVE command. This data is then made available in dialog variable ZEDUSER at the time edit recovery is processed.

You can use EDIT to edit workstation files on the host and host data sets on the workstation. This function is called distributed editing.

The ZWSWFN variable is the workstation working file name that is generated by ISPF. The variable ZLRECL is the LRECL of the host data set being edited. Both can be used in the workstation EDIT parameters field. ISPF interprets any string that starts with an ampersand (&) as a system variable and evaluates it before passing to the workstation command. Strings that do not start with an ampersand are passed as is. The EDIT service edits the host data set or workstation file on the workstation, using the workstation editor configured in the ISPF Workstation Tool Integration Program. For more information about the Integration program, refer to the z/OS ISPF User's Guide Vol II.

Restrictions when using distributed editing:

This type of edit does not support uncataloged data sets.
Take care when uploading to the host files that contain extended ASCII characters. For example, uploading a Microsoft Word *.DOC file to the host, using ISPF Edit to edit it, then saving it, can result in a corrupted file.
Some characters that are normally valid for a directory or file name might not be supported when using distributed editing. For example, the caret symbol ( ‸, or shift-6 in GUI mode) is supported in a directory or file name on Windows but is ignored by some implementations of the TCP/IP File Transfer Protocol.
Some workstation editors might not work for multiple modal invocations. After the first invocation of some editors, any subsequent invocation of the same editor passes control to the first invocation when a command is issued in the second invocation, and the second invocation shuts down.

Besides the Edit program name, you can specify batch commands in the Workstation Edit field. If you have a file transferred to the workstation that you wish to do some work on besides Edit, you can do that in the beginning of the batch file before invoking the editor. Depending on the parameters passed to the batch command, you can also have conditional logic to perform other functions.

Command invocation format


>>-ISPEXEC--EDIT--DATASET(dsname)--+----------------+----------->
                                   '-VOLUME(serial)-'   

>--+----------------------+--+-------------------+-------------->
   '-PASSWORD(pswd-value)-'  '-PANEL(panel-name)-'   

>--+-------------------+--+-----------------------+------------->
   '-MACRO(macro-name)-'  '-PROFILE(profile-name)-'   

>--+---------------------+--+------------------+---------------->
   '-FORMAT(format-name)-'  |        .-NO--.   |   
                            '-MIXED(-+-YES-+-)-'   

>--+-----------------+--+--------------------+------------------>
   |       .-NO--.   |  |          .-YES-.   |   
   '-LOCK(-+-YES-+-)-'  '-CONFIRM(-+-NO--+-)-'   

>--+---------------+--+------+--+----------+-------------------->
   |     .-NO--.   |  '-WRAP-'  '-PRESERVE-'   
   '-WS(-+-YES-+-)-'                           

>--+----------------+--+-------+--+-------------------+--------><
   '-PARM(parm-var)-'  +-ASCII-+  '-LINECMDS(tabname)-'   
                       '-UTF8--'


>>-ISPEXEC--EDIT--DATAID(dsname)--+---------------------+------->
                                  '-MEMBER(member-name)-'   

>--+-------------------+--+-------------------+----------------->
   '-PANEL(panel-name)-'  '-MACRO(macro-name)-'   

>--+-----------------------+--+---------------------+----------->
   '-PROFILE(profile-name)-'  '-FORMAT(format-name)-'   

>--+------------------+--+-----------------+-------------------->
   |        .-NO--.   |  |       .-NO--.   |   
   '-MIXED(-+-YES-+-)-'  '-LOCK(-+-YES-+-)-'   

>--+--------------------+--+---------------+-------------------->
   |          .-YES-.   |  |     .-NO--.   |   
   '-CONFIRM(-+-NO--+-)-'  '-WS(-+-YES-+-)-'   

>--+------+--+----------+--+----------------+--+-------+-------->
   '-WRAP-'  '-PRESERVE-'  '-PARM(parm-var)-'  +-ASCII-+   
                                               '-UTF8--'   

>--+-------------------+---------------------------------------><
   '-LINECMDS(tabname)-'


>>-ISPEXEC--EDIT--WSFN(ws-filename)--+-------------------+------>
                                     '-PANEL(panel-name)-'   

>--+-------------------+--+-----------------------+------------->
   '-MACRO(macro-name)-'  '-PROFILE(profile-name)-'   

>--+---------------------+--+------------------+---------------->
   '-FORMAT(format-name)-'  |        .-NO--.   |   
                            '-MIXED(-+-YES-+-)-'   

>--+-----------------+--+--------------------+------------------>
   |       .-NO--.   |  |          .-YES-.   |   
   '-LOCK(-+-YES-+-)-'  '-CONFIRM(-+-NO--+-)-'   

>--+---------------+--+------+--+----------+-------------------->
   |     .-NO--.   |  '-WRAP-'  '-PRESERVE-'   
   '-WS(-+-YES-+-)-'                           

>--+----------------+------------------------------------------><
   '-PARM(parm-var)-'


>>-ISPEXEC--EDIT--FILE(file-var)--+-------------------+--------->
                                  '-PANEL(panel-name)-'   

>--+-------------------+--+-----------------------+------------->
   '-MACRO(macro-name)-'  '-PROFILE(profile-name)-'   

>--+---------------------+--+------------------+---------------->
   '-FORMAT(format-name)-'  |        .-NO--.   |   
                            '-MIXED(-+-YES-+-)-'   

>--+-----------------+--+--------------------+------------------>
   |       .-NO--.   |  |          .-YES-.   |   
   '-LOCK(-+-YES-+-)-'  '-CONFIRM(-+-NO--+-)-'   

>--+---------------+--+------+--+----------+-------------------->
   |     .-NO--.   |  '-WRAP-'  '-PRESERVE-'   
   '-WS(-+-YES-+-)-'                           

>--+----------------+--+-----------------+--+-------+----------->
   '-PARM(parm-var)-'  '-RECLEN(rec-len)-'  +-ASCII-+   
                                            '-UTF8--'   

>--+-------------------+---------------------------------------><
   '-LINECMDS(tabname)-'

Call invocation format


>>-CALL--ISPLINK--('EDITbbbb'--,--+--------+--,-+-serial-+------>
                                  '-dsname-'    '-'b'----'   

>--,-+-pswd-value-+--,-+-panel-name-+--,-+-macro-name-+--------->
     '-'b'--------'    '-'b'--------'    '-'b'--------'   

>--,-+-profile-name-+--,--+---------+--,-+-member-name-+-------->
     '-'b'----------'     '-data-id-'    '-'b'---------'   

                        .-'NObbbbbb'-.    .-'NObbbbbb'-.   
>--,-+-format-name-+--,-+-'b'--------+--,-+-'b'--------+-------->
     '-'b'---------'    '-'YESbbbbb'-'    '-'YESbbbbb'-'   

     .-'YESbbbbb'-.                                   
>--,-+-'b'--------+--,--+-------------------------+------------->
     '-'NObbbbbb'-'     '-ws-filename-buffer-name-'   

     .-'NObbbbbb'-.                                       
>--,-+-'b'--------+--,-+-'WRAPbbbb'-+--,-+-'PRESERVE'-+--------->
     '-'YESbbbbb'-'    '-'b'--------'    '-'b'--------'   

     .-'YESbbbbb'-.                                    
>--,-+-'b'--------+--,-+-parm-var-+--,--+----------+------------>
     '-'NObbbbbb'-'    '-'b'------'     '-file-var-'   

>--,-+-rec-len-+--,-+-'ASCIIbbb'-+-);--,-+-tabname-+-----------><
     '-'b'-----'    +-'UTF8bbbb'-+       '-'b'-----'   
                    '-'b'--------'


>>-CALL--ISPEXEC--(buf-len,--buffer);--------------------------><

Parameters

dsname

The data set name, in TSO syntax, of the data set to be edited. This is equivalent to the "other" data set name on the Edit Entry Panel. You can specify a fully qualified data set name enclosed in apostrophes (' '). If the apostrophes are omitted, the TSO data set prefix from the user's TSO profile is automatically attached to the data set name. The maximum length of this parameter is 56 characters.

For ISPF libraries and MVS™ partitioned data sets, you can specify a member name or a pattern enclosed in parentheses. If you do not specify a member name or if you specify a member pattern as part of the dsname specification when the DATASET keyword is used, a member selection list for the ISPF library, concatenation of libraries, or MVS partitioned data set is displayed. See the z/OS ISPF User's Guide Vol I for more information about patterns and pattern matching.

Note: You can also specify a VSAM data set name. If a VSAM data set is specified, ISPF checks the ISPF configuration table to see if VSAM support is enabled. If it is, the specified tool is invoked. If VSAM support is not enabled, an error message is displayed.

serial

The serial number of the volume on which the data set resides. If you omit this parameter or code it as blank, the system catalog is searched for the data set name. The maximum length of this parameter is 6 characters.

pswd-value

The password if the data set has MVS password protection. Do not specify a password for RACF-protected data sets.

panel-name

The name of a customized edit panel, created by you, to be used when displaying the data. See z/OS ISPF Planning and Customizing for information about developing a customized panel.

macro-name

The name of the first edit macro to be executed after the data is read, but before it is displayed. See z/OS ISPF Edit and Edit Macros for more information.

profile-name

The name of the edit profile to be used. If you do not specify a profile name, the profile name defaults to the ISPF library type or last qualifier of the "other" TSO data set name. See the z/OS ISPF Edit and Edit Macros for more information.

data-id

The data ID that was returned from the LMINIT service. The maximum length of this parameter is 8 characters.

You can use the LMINIT service in either of two ways before invoking the EDIT service:

You can use LMINIT to allocate existing data sets by specifying a data set name or ISPF library qualifiers. LMINIT returns a data ID as output. This data ID, rather than a data set name, is then passed as input to the EDIT service.
The dialog can allocate its own data sets by using the TSO ALLOCATE command or MVS dynamic allocation, and then passing the ddname to LMINIT. Again, a data ID is returned as output from LMINIT and subsequently passed to the EDIT service. This procedure is called the ddname interface to EDIT. It is particularly useful for editing VIO data sets, which cannot be accessed by data set name because they are not cataloged.

member-name

A member of an ISPF library or MVS partitioned data set, or a pattern. If you do not specify a member name when the MEMBER keyword or call invocation is used, or if a pattern is specified, a member selection list for the ISPF library, concatenation of libraries, or MVS partitioned data set is displayed. See the z/OS ISPF User's Guide Vol I for more information about patterns and pattern matching.

format-name

The name of the format to be used to reformat the data. The format-name parameter is provided to support the IBM® 5550 terminal using the Double-Byte Character Set (DBCS).

YES|NO

For the MIXED parameter, if YES is specified, the EDIT service treats the data as mixed-mode DBCS data. If NO is specified, the data is treated as EBCDIC (single-byte) data. This parameter is provided to support the IBM 5550 terminal using the Double-Byte Character Set (DBCS).

YES|NO

The LOCK parameter is no longer used since the removal of LMF from the ISPF product, but is left in for compatibility purposes. If YES is specified the edit service will fail with return code 12. If you want to be able to specify YES and have the editor ignore the value, change the FAIL_ON_LMF_LOCK keyword value in the ISPF Configuration Table to NO.

YES|NO

For the CONFIRM parameter, if you specify YES and then attempt to CANCEL, MOVE, or REPLACE data while in EDIT mode, ISPF displays a pop-up panel that requires you to confirm the action. Because members or data sets that are moved, canceled, or replaced are deleted, CONFIRM acts as a safeguard against accidental data loss. If you want to terminate the edit session without saving the data, press ENTER. If you made a mistake and want to return to the edit session, enter the END command. If you specify NO as the CONFIRM value, you will not be required to confirm a CANCEL, MOVE, or REPLACE.

ws-filename-buffer-name

Specifies the name of a variable containing the path and the file name in the workstation's file system syntax of the workstation file to be edited. The maximum length of the path and the workstation file name within this variable is 256. If the path is omitted, the working directory configured in the ISPF tool integrator will be inserted in front of the workstation file name to resolve the relative path. For more information see the z/OS ISPF User's Guide Vol II.

YES|NO

For the WS keyword, if you specify YES, the EDIT service edits the host data set or workstation file on the workstation, using the workstation editor configured in the ISPF Workstation Tool Integration Program. For more information see z/OS ISPF User's Guide Vol II. If you specify NO, the EDIT service edits the host data set or workstation file on the host using the ISPF editor.

WRAP

Indicates how the editor should process host data that has been edited on the workstation and now contains records longer than the logical record length of the host data set. Specifying WRAP causes the editor to upload the data to the host data set, wrapping any lines that are longer than the logical record length. Leaving off the WRAP parameter or passing a blank value will cause the editor to display a prompt panel to the user with these options:

upload the data, wrapping any long lines
have the editor create a temporary data set with a logical record length large enough to handle the data, then upload the data to that temporary data set.

This parameter is only valid when WS(YES) is specified.

PRESERVE

When specified, the editor stores the original length of each record in variable-length data sets and when a record is saved, the original record length is used as the minimum length for the record. The editor always includes a blank at the end of a line if the length of the record is zero or eight. Records can be extended by adding nonblank data to the record or by using the SAVE_LENGTH edit macro command. For more information, refer to the z/OS ISPF Edit and Edit Macros.

YES|NO

For the CHGWARN parameter, if you specify YES, the VIEW service gives a warning when the first data change is made, indicating that data cannot be saved in View. If you specify NO, no warning is given. This parameter is ignored for EDIT.

parm-var

The name of an ISPF variable that contains parameters which are to be passed to the initial macro specified by macro-name. The variable value must not exceed 200 bytes in length. If no macro name is specified, parm-var must be blank or not specified.

file-var

The name of an ISPF variable containing the path name for a z/OS® UNIX regular file or directory. If the path name is for a directory, a directory selection list is displayed.

rec-len

A numeric value specifying the record length to be used when editing a z/OS UNIX file. This parameter causes the records to be loaded into the editor as fixed length and saved back in the file as fixed length.

ASCII|UTF8

This parameter can be specified when invoking EDIT to edit data encoded in ASCII (or UTF-8) and the file is not tagged with a CCSID of 819 (or 1208).

When ASCII is specified or the file is tagged with CCSID 819, the editor renders the ASCII data readable by converting it to the CCSID of the terminal. Also, if set for a z/OS UNIX file, the editor breaks up the data into records using the ASCII linefeed character (X'0A') and the ASCII carriage return character (X'0D') as the record delimiter. For z/OS UNIX files, the linefeed and carriage return characters are removed from the data loaded into the editor but written back to the file when the data is saved. This option should not be used when editing workstation files which are converted to EBCDIC when they are loaded from the workstation.

When UTF8 is specified, or the file is tagged with CCSID 1208, the equivalent actions happen, except for UTF-8 instead of ASCII.

tabname

The name of a user line command table to be provided by the service caller.

buf-len

A fullword fixed binary integer containing the length of the buffer parameter.

buffer

A buffer containing the name of the service and its parameters in the same form as they would appear in an ISPEXEC invocation for a command invocation.

Return codes

These return codes are possible:

0

Normal completion; data was saved.

4

Normal completion; data was not saved for one of these reasons.

No data changes were made during the EDIT session. The CANCEL command was used to exit EDIT. Browse was substituted for EDIT because insufficient storage was available to read in the requested data.

12

YES was specified for the LOCK parameter.

14

Member, sequential data set, or z/OS UNIX file in use.

16

Either:

No members matched the specified pattern.
No members in the partitioned data set.

18

A VSAM data set was specified but the ISPF Configuration Table does not allow VSAM processing.

20

Severe error; unable to continue.

Examples

Example 1: Edit a PDS member

This example invokes the EDIT service for TELOUT, a member of the ISPFPROJ.FTOUTPUT data set.

Command invocation

ISPEXEC EDIT DATASET('ISPFPROJ.FTOUTPUT(TELOUT)') WS(YES)

OR

ISPEXEC LMINIT DATAID(EDT) DATASET('ISPFPROJ.FTOUTPUT')
ISPEXEC EDIT DATAID(&EDT) MEMBER(TELOUT) WS(YES)

Call invocation

CALL ISPLINK ('EDIT','ISPFPROJ.FTOUTPUT(TELOUT)',' ',' ',' ',' ',' ',' ',
    ' ',' ',' ',' ',' ',' ','YES');
OR

Set the program variable BUFFER to contain:

BUFFER = 'EDIT DATASET('ISPFPROJ.FTOUTPUT(TELOUT)'') WS(YES)';

Set the program variable BUFFLN to the length of the variable BUFFER. Issue the command:

CALL ISPEXEC (BUFFLN, BUFFER);

Example 2: Edit a workstation file

This example invokes the EDIT service for a workstation file, c:\config.sys, using the ISPF editor on the host.

Command invocation

Set the command variable WSFNNAME to contain:

WSFNNAME='c:\config.sys'
ISPEXEC EDIT WSFN(WSFNNAME) WS(NO)

Call invocation

Set the program variable to contain:

WSFNNAME='c:\config.sys';
CALL ISPLINK('EDIT',' ',' ',' ',' ',' ',' ',
    ' ',' ',' ',' ',' ',' ',' WFSNNAME','NO');

OR

Set the program variable WSFNNAME to contain:

WSFNNAME='c:\config.sys';

Set the program variable BUFFER to contain:

BUFFER='EDIT WSFN(WSFNNAME) WS(NO)';

Set the program variable BUFFLEN to the length of the variable BUFFER. Issue the command:

CALL ISPEXEC(BUFFLEN,BUFFER);

Example 3: Edit a z/OS UNIX file

This example invokes the EDIT service for z/OS UNIX file /u/user1/filea.

Command invocation

FILEVAR='/u/user1/filea'
ISPEXEC EDIT FILE(FILEVAR)

Call invocation

FILEVAR='/u/user1/filea';
CALL ISPLINK('EDIT',' ',' ',' ',' ',' ',' ',
    ' ',' ',' ',' ',' ',' ',' ',' ',' ',' ','FILEVAR ');