AMT Help Files

AMT JCL Library

This page summarizes features and functionalities of the AMT Job Control Language (JCL) Library. The AMT JCL library was made to mimic Mainframe JCL operations in Python. It abstracts JCL logic, making it easier to automate and execute batch jobs outside traditional mainframe environments.

Overview

The AMT JCL Library file is a Python library that provides a high-level interface for interacting with JCL-like job management, file handling, and utility execution in mainframe emulated environments. It wraps and abstracts common JCL operations, making them accessible from Python scripts.

  1. Job and Step Management
    • Job: Represents a batch job, with properties like name, description, start time, and restart information.
    • Step: Represents a step within a job, including file lists, return codes, and conditions.
  2. File Handling
    • File: Abstraction for datasets/files used in JCL steps.
    • File Actions: Support for creating, copying, merging, appending, and deleting files.
    • File Status: Handles file disposition (e.g., SHARED, NEW, OLD, APPEND) similar to JCL DISP parameter.
  3. AMT JCL Functions
    AMT JCL Limits
    AMT JCL does not currently process IDCAMS GDG DEFINE or ALTER statements. Use the GDG Catalog file to apply limits centrally, to manage limits for all GDGs in one place. Existing GDG folders retain their prior gdg_config.yaml value until removed.
    • Implements Python equivalents for common JCL utilities:
      • IEBGENER/ICEGENER: File copy and generation.
      • IEBCOPY: Dataset/member copying and merging.
      • IDCAMS LISTCAT: Catalog listing.
      • DSNUTILB/DSNUPROC: Database utilities.
      • DBUTLTY/PTLDRIVM: Database and SQL utilities.
      • FTP/SMTP: File transfer and email sending.
      • EZACFSM1: Symbol substitution.
  4. AMT JCL Parameter Parsing
    • Functions to convert JCL string parameters (e.g., DISP, COND) into Python values and logic.
    • Handles symbolic environment variables for dynamic substitution.
  5. Job Lifecycle
    • Initialization: Sets up environment, logging, and configuration.
    • Finish/Cleanup: Handles job summary, file closure, and temporary file removal.
    • Restart: Supports job and step restart logic.

JCL Script Example Usage

Visit the AMT JCL Script page for examples on how to utilize AMT JCL.

GDG Catalog File

When a Generation Data Group (GDG) is created for the first time, its folder is initialized using the value from the catalog file. Existing GDG folders are not modified.

If no explicit configuration is provided, the maximum number of file cycles retained for a GDG defaults to 255. Centralized control of per-GDG cycle limits is available through a GDG catalog file referenced by the AMT_JCL_GDG_CATALOG environment variable. The maximum number of cycles is 9999.

The GDG catalog file is a JSON document listing each GDG and the maximum number of cycles to keep. Example:

{
    "A.B.C": {
        "max_number_of_cycles": 7
    },
    "D.E.F": {
        "max_number_of_cycles": 30
    }
}

The AMT JCL library reads this file during initialization and applies the defined maximum number of cycles only to GDGs listed in the catalog. Any GDG not present in the catalog will use the default cycle limit of 255. GDG settings and their values are stored in the gdg_config.yaml file within each GDG folder.

To apply a new cycle limit to an existing GDG, remove its current folder and allow normal JCL execution to recreate it.

External File Transfers

Files can be pulled from, and pushed to AMT. The dropzone setting must be configured with a folder path in the jcl-config.json file. The dedicated dropzone folder is where inbound and outbound files are stored and exchanged.

The following functions can be used in scripts to pull and push files:

Function Parameters Description
pull_file_from_amt pullfile: The file identifier.
step_name: The step name for file control (default: 'PS010').
logger: Optional logger instance.
ebcdic: If True, convert the file from EBCDIC to ASCII before pushing (default: False). 		Pull a file from AMT storage to the dropzone, handling GDG cycles and merging. Examples of file identifiers:
  • CYCLEFILE.G000XV00: Pull a cycle file.
  • FOLDER.MYFILE: Pull a regular file.
  • CYCLEFILE.MYFILE: Pull an entire GDG, all cycle files are merged into one file.
push_file_to_amt pushfile: The file identifier.
step_name: The step name for file control (default: 'PS010').
logger: Optional logger instance.
ebcdic: If True, convert the file from EBCDIC to ASCII before pushing (default: False). 		Push a file from the dropzone to AMT storage.

Functions

Function Arguments Description
initialize calling_file Initialize library, environment & logging.
parse_command_line_args Execute jobs in the AMT Java environment through scripts.
add_job name, description Create and register a new job.
set_restart restart_step, restart_batch_id Configure restart parameters for script run.
finish_job Finalize job, close files, set return codes.
terminate_step ex Handle step termination on exception.
write_job_summary Add entry to job summary file/log.
set_env_symbol symbol, value Store environment symbol for later substitution.
resolve_env_symbol symbol Retrieve environment symbol value.
start_procedure name, set_file_control, step_conditions Begin execution context for a procedure.
remove_file file_name, original_file_name Remove a physical file by logical mapping.
remove_file file, delete_empty_folders Remove file object; optionally prune empty folders.
get_unique_string Generate random hex string.
convert_to_unquote_string input_string Return unquoted version of string.
find_file file Check if file exists (boolean).
find_file_in_list logical_name Locate file by logical name in list.
invoke_sort sort_step, input_file, sortin_file, sortout_file Invoke a sort utility step, processing input files and producing sorted output.
amt_iceman step
amt_icetool step
prepare_toolin_command
invoke_sorting step, sort_commands Execute sorting operations using specified sort commands for the given step.
invoke_dmbatch step, input_file
amt_dmbatch step, input_file
amt_ndmbatch step, input_file
build_ftp_commands_from_dmbatch submit Create FTP command list from submit params.
invoke_dsnutilb step Run DSNUTILB database utility.
amt_dsnutilb step
amt_dsnuproc step
amt_dbutlty step
amt_ptldrivm step
export_file export_file Export a file or dataset to an external location or format.
merge_files in_file, out_file Merge multiple files into one.
set_global name, value Set global variable/context value.
get_returncode step Get return code for step.
amt_iefbr14 IEFBR14 (no-op) implementation.
amt_iebgener input_file, output_file, definitions_file Copy/generate dataset (IEBGENER/ICEGENER).
check_destination input_file, dest_key Validate destination key for file transfer.
amt_icegener inputFile, outputFile, definitionsFile ICEGENER variant for generation.
amt_idcams input_file IDCAMS functionality (LISTCAT etc.).
amt_listcat catalog, entries, level, out_file List catalog entries.
amt_iebcopy IEBCOPY implementation.
merge_members input_dts, output_dts, members Copy selected members between datasets.
copy_folder input_dts, output_dts Copy all members from source to target.
new_record_file file_name, record_size, key_start, key_length Create indexed record file (DEFINE).
amt_print dataset, count Print dataset records (limited).
join_paths path
get_datetime
convert_directory_name name_in Convert directory name to Windows format.
get_temp_path
abort message Abort processing with error.
terminate_job message Terminate entire job.
cleanup_job completed Cleanup after job end.
close_all_files completed, file_list, end_of_job Close all open file handles.
format_out_record in_record, fields, error_code Format output record fields.
copy_records input_file, output_file, fields, error_code Copy record set to target.
remove_empty_folders path Delete empty folders under path.
remove_folder folder_to_delete Remove folder recursively.
new_output name, default, class_name, forms, writer, copies, fcb, form_definition, page_definition, dept, title, addr, out_name Create new output (print) definition.
xcopy src, dest Copy files or folders from source to destination.
get_virtual_files step, file_list Retrieve virtual file definitions.
copy_file source, target Copy file from source to target.
replace_file in_file, out_file Replace file contents.
copy_reproduce_records in_file, out_file Copy records reproducing original set.
invoke_append_file source, target Append source file to target.
send_print_file source_file, printer Send print file to printer.
amt_ikjeft_process input_file, ikj_type
amt_ikjeft01 input_file
amt_ikjeft1b input_file
amt_ftp input_file, input_data, sys_print, output Execute FTP file transfer.
amt_ftpiproc input_file, input_data, sys_print, output FTPIPROC utility (FTP wrapper).
append_file_to_instream file_name, instream_array Append file contents to instream array.
amt_pkzip command_file, archive_file Create ZIP archive.
append_path_separator path Ensure trailing path separator.
amt_get_date format Return date with format.
amt_sqlload
get_unique_number Generate unique integer value.
get_unique_printfilepath filename Generate unique print file path.
trim_to_length strings, length Trim list of strings to length.
jcl_string_to_value jcl_kind, jcl_value Parse JCL param into value.
jcl_string_to_disp_value string_value Parse DISP value to FileStatus.
jcl_string_to_cond_value string_value Parse COND to boolean.
jcl_create_condition code, operator Create boolean condition object.
merge_with_virtual_files file Merge virtual file definitions.
write_jobsummary message Write line to job summary.
write_error message Write error line to log.
amt_ezacfsm1 currentStep Substitute MVS symbols.
start_dynamic_jcl name Start dynamic JCL job.

Functionality Summary

Contents

arrow_back Previous Next arrow_forward