Storage Toolkit limitations and hints

This topic describes limitations, hints and other considerations for the Storage Toolkit. You can avoid problems by remaining aware of these issues. Also remain aware of other issues documented throughout this chapter.
  • Data sets not locked: The Storage Toolkit enables you to click the Edit JCL button in the Create Batch Job dialog box, and edit a data set that is located in the mainframe environment. However, you must ensure that no one accesses the data set at the same time, because the data set is not locked during your editing session. Another user could edit the data set, for example, in TSO using ISPF, during your editing session. That user would not see a "data set in use" message; if he saves his changes before you save yours, your changes overlay his. If that user is still editing the data set when you attempt to save your changes, the attempt to save your changes fails. The results of each editing session might be unpredictable depending on the scenarios and editing tools that the other user uses.
  • EBCDIC code page 037 only: The JCL editor provided by OMEGAMON® for Storage on z/OS® supports EBCDIC code page 037 only. The editing or authoring of JCL in other code pages such as EBCDIC code page 930 (in other words, Japanese EBCDIC) is not supported.
  • Storage Toolkit first and last steps: In every batch job, the Storage Toolkit inserts a Toolkit-specific first step that sets up a monitor over the steps in the job. The monitor collects targeted output from the steps in the job. The Storage Toolkit also appends a last step to the end of the job. The last step collects targeted SYSOUT from the previous steps along with the JES output and the return code. It also notifies the monitoring agent that the batch job is complete. The Toolkit-specific first step is inserted immediately before the first EXEC, PROC, or INCLUDE statement that it locates in the JCL.
    Note: If your JCL has an INCLUDE statement before an EXEC or PROC statement, the INCLUDE member must not contain JCL statements, such as JCLLIB, that must precede the first job step. Because the Toolkit first step is inserted before the INCLUDE, the batch job fails in this case.
  • Using the null statement to mark the end of a job: When you use the Create Batch Job dialog box to execute user-defined JCL, the Storage Toolkit generates a copy of your JCL to which it adds a Toolkit-specific first step and a Toolkit-specific last step. If your JCL ends with the null JCL statement denoting end of job, 
    //
    that null statement is removed from the generated JCL because the job does not end until after the Toolkit-specific last step runs.
  • Conditional processing: Do not specify a COND parameter on the JOB card or on an EXEC statement that might cause the Storage Toolkit steps that were inserted into the JCL to not run. If you use the COND parameter or you use IF/THEN/ELSE/ENDIF statements, you must ensure that the Storage Toolkit first and last steps run.
  • No support for multiple jobs in user-defined JCL: When you use the Create Batch Job dialog box to execute user-defined JCL, the JCL must not include multiple jobs. The Storage Toolkit does not support this type of JCL. Results are unpredictable.
  • JOB card:
    • When you use the Create Batch Job dialog box to execute user-defined JCL, the batch job is submitted using the Replacement JCL JOB card which you specify on the JCL tab. This overrides a JOB card that might be present in the JCL. If you do not specify a Replacement JCL JOB card, your installation-specific JOB card is used.
    • Do not specify a CLASS or a TYPRUN option on your JOB card that just copies or scans the job. Because the batch job does not execute, you action request remains in the EXECUTING state. You must cancel the request to release the thread and resources associated with it and to remove it from EXECUTING state.
    • Do not specify a COND parameter on the JOB card that might cause the Storage Toolkit first and last steps inserted into the JCL to not run.
    • When you request the JES output be copied for later viewing, make sure the MSGLEVEL on your JOB card is set to the level of output that you desire.
    • When you specify your JOB card, consider assigning it a unique job name. If the name matches a batch job that is executing on your z/OS system, your job might be delayed until the executing job completes. To prevent this, assign a unique name to your job.
  • Using a PROC in user-defined JCL: When you use the Create Batch Job dialog box, you can run JCL that executes a procedure, however the Storage Toolkit might not be able to properly copy the contents of files associated with steps in that procedure:
    • The procedure can be instream or in a system or private procedure library. If you use a private procedure library, you must ensure the JCLLIB statement precedes the Storage Toolkit first step.
    • You can request files that are referenced in the procedure be copied for later viewing, but with certain limitations:
      • The step name is the step name in your JCL that executes the procedure. You cannot specify the step names that are in the procedure itself.
      • If the procedure consists of a single step, the contents of the requested files is returned.
      • If there are multiple steps in the procedure, the contents of a requested data set or DD name that references a data set is returned for each procedure step (in other words, multiple times). The contents of a DD name that is routed to SYSOUT is returned for each procedure step in which the SYSOUT DD name is defined (ie., one or more times).
  • Use step names in user-defined JCL: Do not include steps in your user-defined JCL without step names, if you intend to copy files for later viewing that are associated with those steps. The Storage Toolkit requires a step name.
  • /*XMIT: Do not use the /*XMIT statement in any of your JCL. The Storage Toolkit does not support this. Results are unpredictable.
  • DYNAMNBR: If you submit user-defined JCL that allocates data sets, be aware that the Storage Toolkit allocates data sets in each step, too. If necessary, you might need to use the DYNAMNBR parameter on your EXEC statement to allow for your data sets and 3 Storage Toolkit data sets.
  • JCL errors: The Storage Toolkit last step appended to the end of each batch job notifies the monitoring agent when the batch job completes. When this occurs the action request that is pending completion of the job is updated with the results of the batch job. If the last step in the batch job does not run, for example, the batch job failed with a JCL error or conditional processing bypassed the last step, the action request remains in an EXECUTING state. If you determine that an action request is in EXECUTING state longer than you anticipate, you must check the status of the batch job on the z/OS system. If the job failed such that the last step did not run, you must cancel the execution of the action request in the Tivoli® Enterprise Portal. This releases the thread and resources associated with the request and removes it from EXECUTING state. You can then determine why the job failed, correct the error and resubmit the request.
  • Return codes: Certain return codes, which are generally paired with a status, are set by the Storage Toolkit when it detects an error processing an action request. The following table lists common return codes and their corresponding status:
    Table 1. Common Storage Toolkit return codes
    Return code Status
    117 This status typically indicates that the JCL exceeds 72 characters when the substitution variables are applied. It might also indicate other JCL-related errors, such as a missing JOB card, or another data set requiring variable substitution that exceeds 80 characters when the substitution variables are applied.
    119 The User Data Server has ended abnormally or the batch job has ended, but the Storage Toolkit is unable to determine the return code.
    121 Authorization has failed.
    123 A data set error has occurred, such as the data set containing your JCL does not exist. Messages in the RKLVLOG of the Tivoli Enterprise Monitoring Server might help you analyze this result.
    125
    The execution of the action request was stopped because the action request was associated with a set of groups that did not exist or were empty at the time of execution. The status that is displayed in the Result Summary workspace is set to one of the following values:
    NonexistentGroups
    Indicates that none of the groups associated with the request existed.
    EmptyGroups
    Indicates that all of the groups associated with the request were empty.
    BadGroups
    Indicates that a combination of empty and missing group errors affected the entire set of groups. This status value might also indicate that some other error was detected when the groups were processed. Review the messages in the RKLVLOG to assist your analysis of the results.
    Note: Groups might be empty because a collection is running or has not yet run. If so, retry the request when the collection completes.
    If you see a return code that does not look familiar, you might want to convert it to its hexadecimal equivalent, because the code might indicate an abend in the batch job. For example, a return code of 193 is the same as x'0C1'.
  • Variable substitution and line limits: Substitution variables that are defined through the Storage Toolkit are replaced when the action request runs. The Storage Toolkit creates temporary data sets to contain the updated statements.
    There are two basic categories of data sets (JCL and Other) that are updated with substitution variables. The Storage Toolkit processes them as follows:
    • JCL data set: Variable substitution is applied to all components of the batch job, including the JOB card, extra JCL, the Toolkit-specific steps, and the body of your JCL along with any instream data sets. The Storage Toolkit interprets column 72 as a continuation character and preserves its contents. The data between columns 2 and 71 might shift left or right depending on the size of the variable name and its substitution value. If the data shifts beyond column 71, the request fails. The return code for the request is set to 117 and the status for this execution isInvalidJCL . You must perform these actions:
      • Verify the substitution variables and values are correct and do not have unintentional consequences to the components of the batch job
      • Correct the JCL to ensure that no line exceeds the limit.
      The action request may also fail with return code 117 if any lines in the original components of the batch job exceed 80 characters.
    • Other data set: Variable substitution is applied to all records in other data sets that you specify as needed by the job that also contains substitution variables. The toolkit makes no assumptions about the contents of the data set and considers each line, from column 1 to column 80, as a line of data. Variable substitution may cause the data in columns 2 through 80 to shift left or right depending on the size of variables names and their values. If the data shifts beyond column 80 (excluding trailing blanks), the request fails. The return code for the request is set to 117 and the status for this execution is InvalidJCL. You must perform these actions:
      • Verify that the substitution variables and values are correct and do not have unintentional consequences to the contents of the data set.
      • Correct the contents of the data set to ensure that no line exceeds the limit.
  • Validating JCL: When you write JCL for use in the Create Batch Job dialog box, always check the validity of the statements before you submit the batch job. For example, when you edit JCL in the Edit JCL dialog box, consider whether line lengths will exceed the 72-byte limit after variable substitution is performed. When substitution variables are replaced in the JCL at execution time, resultant JCL lines that contain more than 72 bytes causes the JCL to not be submitted. A status of InvalidJCL is displayed in the Result Summary workspace for the action request.
  • Reserved variable names: The Storage Toolkit reserves the following variable names. You must not use these names for your own variables:
    %%KS3TK_CMD_DSN%%
%%KS3TK_HSM%%
%%KS3TK_DYNAMNBR%%
  • Fully Qualified Datasets needed by the job that also contain substitution variables: When you use the Create Batch Job dialog box, you can specify additional data sets that contain substitution variables. The Storage Toolkit creates a temporary data set with the updates and replaces the name of the original data set with the temporary one in its copy of your JCL. In order for the names to be replaced, the data sets must be referenced in your JCL; they cannot be in cataloged procedures or INCLUDE members that your JCL might use.
  • JES output:
    • The techniques that the Storage Toolkit uses to collect JES logs and system-handled output data sets (SYSOUT) require your z/OS operating system use JES2.
    • Because the Storage Toolkit last step collects JES output just before the batch job ends, some of the messages you normally see in the JES logs such as the job start (IEF375I) and job end (IEF376I) messages are not included in the JES output.
  • Mainframe commands:
    • Mainframe console commands are submitted through an SDSF batch job interface. A forward slash (/) must precede the command, as in this example, which cancels a time-sharing user (tso_user_ID): 
      /C U=tso_user_ID
    • Command output is not returned for Mainframe console commands because execution of the command is not synchronized with execution of the batch job.
    • Because execution of the command is not synchronized with execution of the batch job, the return code associated with the action request reflects the submission of the command to the SDSF batch job interface. It does not reflect the execution of the command itself.
    • Because the Storage Toolkit uses SDSF, your z/OS operating system must use JES2.
  • Shared DASD: The temporary data sets that the Storage Toolkit creates to contain the generated JCL, the results data set, and other files are shared between the Toolkit and the batch job. Because the batch job can run on a z/OS system in your SYSPLEX different from the one where the monitoring agent runs, the temporary data sets must be created on DASD shared across the systems. Your installation can control the location of the temporary data sets using options in PARMGEN. These options also control the location of data sets created using the Edit JCL option in the Create Batch Job dialog box.

    In addition, when you use the Create Batch Job dialog box, you specify the data set containing the JCL you wish to submit and, optionally, specify data sets needed by the job that also contain substitution variables. These data sets must be cataloged and located on on-line DASD that is accessible to the z/OS system where the monitoring agent runs.

  • APF-authorized load library on remote systems: The Storage Toolkit inserts a first step and last step into every batch job. These steps run Toolkit code that is located in the TKANMODL load library for your installation's run time environment. The load library must be APF-authorized. If the batch job runs on the same z/OS system as the monitoring agent, the load library is normally already APF-authorized. If your batch job runs on another z/OS system in your SYSPLEX, you must ensure the load library is APF-authorized on that system as well. The load library must also be located on DASD that is shared across the systems.
  • Unprintable characters: You must ensure that the files you specify as Files whose contents should be copied for later viewing on the Create Batch Job dialog box or the output from a command on the Issue Command dialog box will contain character data only. If the files or command output contain unprintable characters (for example, hexadecimal data), these characters might not display properly in the Storage Toolkit Result Detail workspace.
  • Checkpoint dataset storage exhausted: When you submit an action request, information about the request is stored in the checkpoint database. When the request completes, results of the execution are also stored. The information stored in the checkpoint database includes elements such as:
    • The name and description of the request
    • The time the request was submitted and the time it completed
    • The resources associated with the request
    • The return code from the execution of the request
    • The output produced by the execution of the request, which might include:
      • Command output
      • Files copied for later viewing
      • The submitted JCL
      • The JES files produced by the batch job.
    The Storage Toolkit checkpoint database is allocated and initialized when the runtime environment is created. This database is never extended. You must ensure that sufficient space exists for the activities of the database. Otherwise, the database can run out of space. You can remove the requests and the results when you no longer need them. You can also use options on the General tab of the Storage Toolkit dialog boxes to help you manage the results.
    Note: If the results from the execution of an action request exceed the free space available in the checkpoint database, the output is lost entirely. The error message KS3T830E SERVICE CHECKPOINT DATASET STORAGE EXHAUSTED in the RKLVLOG of the Tivoli Enterprise Monitoring Server indicates this condition. The IBM® OMEGAMON for Storage on z/OS: Troubleshooting Guide provides further information about this issue.
Related information:
Using the Storage Toolkit