ZEXEC: Process a command file

Use this command to process a command file that is stored on the z/TPF file system. A command file is a file that contains commands to run in sequence and is ideal for setting up or initializing a system that requires many commands to produce the needed environment.

Last updated

  • Changed in 2019.
  • Changed for PUT15.
  • Changed for PUT14 (information only; no code change).
  • Changed for PUT09.

Requirements and restrictions

  • You can enter this command only when the z/TPF system is in 1052 state or higher.
  • Command prefixing, which redirects a command to a processor or subsystem user other than the processor and subsystem user on which the ZEXEC message was started, is not supported.
  • If a command generates output that requires the ZPAGE command to continue, the ZPAGE command must be entered manually or through console automation. ZEXEC processing does not initiate the ZPAGE command.
  • When you create the command file, consider the following:
    • You can create the command file on any platform, but it must reside on the z/TPF file system before processing with the ZEXEC command. (You can use File Transfer Protocol (FTP) to transfer the command file to the z/TPF file system).
    • Any z/TPF-supported command can be used in the command file. The command file must contain one z/TPF command in EBCDIC coding per line. Each command contained in the file can be up to 1020 bytes in length, which is equal to the system message processor (SMP) limitation.
    • Two forward slashes (//) in the first two columns of a line indicate that the line is ignored and can be used as a comment line. Blank lines are also ignored.
    • The first character of each line in the command file must be a valid, alphanumeric character or an at sign (@) in EBCDIC coding.
    • Commands in the command file can be in uppercase or lowercase characters. See the information for each command for any requirements or restrictions related to individual commands, including case-sensitivity and state requirements.
    • A line that starts with an at sign (@) represents the start of reserved ZEXEC script directives for special processing. The following table shows supported script directives:
      Table 1. Supported script directives
      Directive format Description
      @sleep slsec Specifies the amount of time, in seconds, that you want the script to pause before execution continues from the point that the directive is specified. Specify a value in the range 0 - 65535.
      @set pause psec Specifies the amount of time, in seconds, that you want the script to pause after each command before execution continues to the next command. If you specify a value of 0, the script does not pause after each command. If you do not code this directive, the script pauses for 1 second after each command.

      The directive takes effect where it is specified in the script until the end of the script or until another @set pause directive is issued.

      @set timeout tsec Specifies the amount of time, in seconds, that you want the script to wait for a command to return before issuing an error and stopping the script. If you specify a value of 0, the script never times out. If you do not code this directive, the timeout value is 30 seconds.

      The directive takes effect where it is specified in the script until the end of the script or until another @set timeout directive is issued.

Format

Read syntax diagramSkip visual syntax diagramZEXEC  FILE-' path'
FILE-path
Specifies the name of the command file that contains the commands to run, where path is the path name of the command file.
  • The path of the file is case sensitive.
  • Specify the path name as an absolute path. If you do not specify the path name as an absolute path the specified path name is relative to the path defined in the TPF_CWD_PATHNAME environment variable (defined in the CENV segment or UENV user exit).
  • The single quotation marks around path allow you to use path names that have one or more spaces in the directory or files names. If your path does not contain any spaces, you can omit the single quotation marks.

Additional information

  • Online help information is available for this command. To display the help information, enter one of the following:
    • ZEXEC HELP
    • ZEXEC ?
  • Responses to the commands in the processed command file are returned to the terminal that originally ran the ZEXEC command.
  • If the @set pause directive is coded with a value of 0, the console might display the next command that is processed before any messages for the previously completed command are displayed.
  • Commands in the command file run in sequence. Each individual command in the file is run only after the ECB that is created for the previous command exits. By default, if a command does not complete within 30 seconds, the command file stops processing and no subsequent commands are run. You can use the @set timeout directive within the script to change the timeout value.
  • If another ZEXEC script is called from within a ZEXEC script, the commands in the script that is called do not inherit the @set pause or @set timeout directive that is set by the calling ZEXEC script.

Examples

In the following example, the ZEXEC command processes the myfile.txt file that resides in the /etc directory. The information requested by each of the commands in the command file is returned to the console that ran the original ZEXEC command.

In this example, the myfile.txt file contains the following commands. The comments describe the processing for each command.

// Change the default pause time after every comment from the default
// value of 1 second to 0 seconds (no pause).
@set pause 0

// Display status information about the z/TPF system.
zstat u

// Pause processing for 20 seconds
@sleep 20

// Display the current system operating state.
zdsys

// Display information about ECBs that are in use.
zdecb

// Set the default timeout value of subsequent commands from the default
// value of 30 seconds to 60 seconds.
@set timeout 60

// Run a Java application that sleeps for 45 seconds.
zfile java –jar /tmp/sleep.jar 45

// Reset the timeout value to 30 seconds for subsequent commands.
@set timeout 30

// Display the status of all the defined tape devices.
zdtap
User:   zexec file-'/etc/myfile.txt'                                       

System: CSMP0097I 16.41.46 CPU-B SS-BSS  SSU-HPN  IS-01                    
        EXEC0001I 16.41.46 COMMAND FILE /etc/myfile.txt PROCESSING STARTED+
        CSMP0097I 16.41.46 CPU-B SS-BSS  SSU-HPN  IS-01          
        EXEC0010I 16.41.46 PROCESSING ZEXEC DIRECTIVE -
        @SET PAUSE 0+                                                      
        CSMP0097I 16.41.46 CPU-B SS-BSS  SSU-HPN  IS-01                    
        EXEC0009I 16.41.46 PROCESSING COMMAND -
        ZSTAT U+                                                           
        CSMP0097I 16.41.46 CPU-B SS-BSS  SSU-HPN  IS-01                    
        EXEC0010I 16.41.46 PROCESSING ZEXEC DIRECTIVE -
        @SLEEP 20+                                                         
        CSMP0097I 16.41.46 CPU-B SS-BSS  SSU-HPN  IS-01                    
        STAT0039I 16.41.46 SYSTEM UTILIZATION DISPLAY
        STATIC POWER SAVE MODE - SYSTEM AT 100 PERCENT
        NUM  ADR  UTIL/ ADJ  CROSS READY INPUT   VCT SUSPD DEFER ACT-ECB S   PSU  LPUU
        IS- 1 00    .4/   .2     0     1     1     0     0     0      8 CU     .4   .0
        END OF DISPLAY+                                                    
        CSMP0097I 16.42.06 CPU-B SS-BSS  SSU-HPN  IS-01                    
        EXEC0009I 16.42.06 PROCESSING COMMAND -
        ZDSYS+                                                             
        CSMP0097I 16.42.06 CPU-B SS-BSS  SSU-HPN  IS-01                    
        DSYS0001I 16.42.06 THE SYSTEM IS IN NORM STATE FOR SUBSYSTEM BSS   
                           ON CO0901   CPU-B  26FEB                        
        END OF DISPLAY+                                                     
        CSMP0097I 16.42.06 CPU-B SS-BSS  SSU-HPN  IS-01                     
        EXEC0009I 16.42.06 PROCESSING COMMAND -
        ZDECB+                                                              
        CSMP0097I 16.42.06 CPU-B SS-BSS  SSU-HPN  IS-01                     
        EXEC0010I 16.42.06 PROCESSING ZEXEC DIRECTIVE -
        @SET TIMEOUT 60+                                                    
        CSMP0097I 16.42.06 CPU-B SS-BSS  SSU-HPN  IS-01                     
        EXEC0009I 16.42.06 PROCESSING COMMAND -
        ZFILE JAVA -JAR /TMP/SLEEP.JAR 45+    
        CSMP0097I 16.42.06 CPU-B SS-BSS  SSU-HPN  IS-01                     
        DECB0014I 16.42.06 DISPLAY ECB SUMMARY           
        ECB ADDR  SSU IS  PGM     TRC MIN SC  ORIGIN   I H      DSP  SVC    
        12666000 HPN   1 CSL2    CSL2  76 18 CREM CSL5 1          0 EVNWC   
        1265D000 HPN   1 CSL2    CSL2  76 18 CREM CSL5 1          0 EVNWC   
        1261E000 HPN   1 CSL2    CSL2  76 18   CXFR    1          0 EVNWC   
        12687000 HPN   1 CSL2    CSL2  76 18   CXFR    1          0 EVNWC   
        12633000 HPN   1 CSL2    CSL2  76 18   CXFR    1          0 EVNWC   
        TOTAL       43                                                      
        END OF DISPLAY+                                                     
        CSMP0097I 16.43.01 CPU-B SS-BSS  SSU-HPN  IS-01                     
        FILE0001I 16.43.01 START OF DISPLAY FROM java -jar /tmp/sleep.jar 45
        Sleeping for 45 seconds                                   
        END OF DISPLAY+                                                     
        CSMP0097I 16.43.01 CPU-B SS-BSS  SSU-HPN  IS-01                               
        EXEC0010I 16.43.01 PROCESSING ZEXEC DIRECTIVE -
        @SET TIMEOUT 30+  
        CSMP0097I 16.43.01 CPU-B SS-BSS  SSU-HPN  IS-01                               
        EXEC0009I 16.43.01 PROCESSING COMMAND -
        ZDTAP+                               
        CSMP0097I 16.43.01 CPU-B SS-BSS  SSU-HPN  IS-01                               
        EXEC0002I 16.43.01 COMMAND FILE /etc/myfile.txt PROCESSING COMPLETED+         
        CSMP0097I 16.43.01 CPU-B SS-BSS  SSU-HPN  IS-01                               
        COTD0002I 16.43.01 DTAP      -TAPE STATUS                                    
        ADDRESS   NAME   SSU    STATUS   TPIND    VOLSER  FORMAT    #BLOCKS LDR  QUEUE
        0430     RTA    BSS      AO    00 81 20  Z00005  38K             5 YES      0                                                                          
        END OF DISPLAY+