Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hypercubic.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Datasets are files, with structure

A dataset is the z/OS equivalent of a file. The naming convention is dot-separated: 
ACME01.SOURCE.COBOL
Every component is up to 8 characters, and the whole name is up to 44. The first component is the HLQ (High-Level Qualifier), usually your TSO user ID. Everything after that is your choice, by convention. But datasets aren’t just files. They have structure:
AttributeWhat it isExample
DSORGOrganization — sequential or partitionedPS (sequential), PO (partitioned)
RECFMRecord format — how records are storedFB (fixed block), VB (variable block), U (undefined)
LRECLLogical record length in bytes80 for source code, 133 for print output
BLKSIZEPhysical block sizeUsually a multiple of LRECL
A PDS (Partitioned Data Set, DSORG=PO) is the closest thing to a directory. It contains named members, each up to 8 characters, each a sequential file. You write ACME01.SOURCE.COBOL(CBACT01C) to reference a member. A PS (sequential dataset) is a flat file with no members.

​
VSAM

VSAM (Virtual Storage Access Method) datasets are mainframe-native indexed storage. The most common type is KSDS (Key-Sequenced Data Set): records stored in primary-key order with an index for fast lookups. Most production data on a mainframe lives in VSAM. Hopper reads it via data taps:
  1. Snapshot the VSAM records into a sequential dataset (using IDCAMS REPRO under the hood)
  2. Bring the snapshot to your laptop
  3. Decode each record using a COBOL copybook (the schema definition)
  4. Store the decoded rows locally so you can query with SQL

​
EBCDIC vs. ASCII

Mainframe datasets are stored in EBCDIC, not ASCII or UTF-8. The most common code page is cp037 (US English). Hopper handles the translation automatically:
  • Reading text datasets: fetched in ASCII mode; the host transcodes EBCDIC → ASCII before sending.
  • Reading binary datasets (like VSAM snapshots): fetched in binary; Hopper decodes EBCDIC fields per the copybook.
  • Writing text: Hopper transcodes ASCII → EBCDIC on the way up.
The conversion is driven by the mainframe’s FTP CCSID setting. If text comes back garbled, the fix is usually on the host side, not in Hopper.

​
Jobs are batch work

A job is a unit of batch work submitted to JES (Job Entry Subsystem). Each job is described in JCL (Job Control Language), a small DSL that says “run this program with these inputs and outputs.” A minimal JCL job: 
//ACME01J JOB CLASS=A,MSGCLASS=H,NOTIFY=&SYSUID
//STEP1    EXEC PGM=IEFBR14
//SYSPRINT DD   SYSOUT=*
This says: “submit a job named ACME01J, run the program IEFBR14 (which does nothing — useful for allocating datasets), and write any console output to spool.” A real job, say compiling COBOL, has more steps: compile, link-edit, and run.

​
The job lifecycle

When you submit a job:
  1. JES queues it. The job sits in the input queue until JES dispatches it.
  2. Steps execute. Each step runs in turn. If one fails (return code ≥ 8), subsequent steps may be skipped depending on COND= settings.
  3. Spool accumulates. Output from each step goes to spool files (one per DD SYSOUT=*).
  4. The job completes. Either successfully (RC=0) or with an error.
You don’t need to open SDSF. Submit jobs from chat or the terminal, watch them in the Jobs panel as their status updates, and ask the agent to pull spool or diagnose failures when something goes wrong.

​
CICS is online, not batch

CICS (Customer Information Control System) is the mainframe’s transaction processing system, the runtime behind the online applications that bank tellers and call-center agents use. Unlike JES jobs, CICS transactions are interactive: you type a transaction code on a 3270 screen, the program responds in milliseconds, you respond, and the chain continues. Hopper has CICS-specific tools: signon, run a transaction, install a resource, run a CEDA define. CICS support is optional; if your mainframe doesn’t run CICS, ignore this section. Configure CICS credentials and library paths under Settings → CICS in the desktop app.

The AI agent

How the agent uses these primitives to do work for you.

Tools

What the agent can do and how Hopper keeps you in control.