1. TSDSUTIL Program Rules

Data/code --- All data definitions precede START. After START, no new data definitions except literals.
Minimum program --- START , ... END ,
Code base --- None. TSDSUTIL does not assemble machine code; a base register for CODE is neither required nor supported.
USING --- DSECTs only. DROP Rn[,Rn...] removes active DSECT USING associations (R1--R15).
Addressing --- Symbolic address or S/370 D(B) / D(X,B) where allowed.
Source --- * in column 1 = comment; trailing + = continuation; continuation inserts no punctuation (required commas remain explicit); adjacent quoted fragments concatenate; symbols are case-insensitive.
Labels --- 1--63 chars; first A-Z @ $ # _; remaining may also contain digits; globally unique.
Character set --- EBCDIC CP037 default.
Addressing model --- 24-bit virtual addresses; 32-bit GPRs; unaligned operands generally permitted.
Storage --- LOWMEM 000000–000FFF read-only; DATA starts 001000; CODE F00000–FFFFFF, first instruction F00002.

Quoted text: Single (') and double (") quotes are interchangeable delimiters. The other quote character may appear literally inside the string. Double the delimiter to include it literally; e.g. " '", ' "', ' '' ', " "" ".

DC / DS: C | X | B | H | F | D | FD | A | AL1 | AL2 | AL3 | AL4 | CLn | P | PLn
CL/XL/BL/PL explicit lengths also accept an immediate absolute expression, e.g. CL(FLEN) or XL(L'AREA+8).
DS 0type may define aligned code labels · EQU length 0 · ORG data/DSECT only · literals e.g. =C'ABC', =F'10'.

2. Built-in Macros

$ASSERT left,EQ | NE | GT | GE | LT | LE,right --- Assertion failure ABENDs SYSTEM EEE.

$DFMT dsect,address --- Display storage using DSECT; explicit address, USING ignored.

$DUMP address,length --- Dump storage.

$EOJ value | $EOJ (register) | $EOJ , --- Terminate and set completion code. Null operand uses current R15; $EOJ , = $EOJ (R15).

$LINENO , --- Current source/listing line returned in R15.

$PRINT 'quoted-text' | $PRINT text-address,text-length --- Print EBCDIC text plus newline.

$RAND , --- Next 32-bit pseudo-random value returned in R1; R15 is unchanged.

$READ dcb,buffer,max-length --- Read one physical tape block. R1=full block length; R15=status. See §7.

$CONTROL dcb,TYPE=BSB | BSF | FSB | FSF[,COUNT=value | (register)] or dcb,TYPE=REWIND --- Physical AWS tape positioning for an open BLP R | W | RW DCB. R15=status; 40=BOT boundary, 16=EOT/EOI boundary, 12=tape mark on block spacing.

$REGS , --- Display R0--R15; registers/CC unchanged.

$RESTORE , --- Restore all 16 GPRs from the top $SAVE frame and pop that frame; CC unchanged.

$RETURN [ (r1 [,r2]) ] --- Restore registers from previous $SAVE, then return through restored R14. Listed register(s) are not restored. Exceptions are limited to R15, R0, R1 and supported combinations.

$SAVE , --- Push all 16 GPRs; registers/CC unchanged.

DEVTYPE ddname,return-area

Returns an 8-byte simulated device description for the DDNAME in an 8-byte blank-padded field. R15=0 for a defined DD and R15=4 if the DDNAME is undefined. Resource values are 3210800300007FF8 for 3420-style AWS tape, 0000010200007FF8 for DATA/simulated SYSIN, 0000010300007FF8 for Linux/PATH, and all zero for defined DUMMY. The return area is cleared before DD lookup.

RDJFCB dcb,jfcb-area

Returns a zero-initialized 176-byte JFCB-compatible copy for the DCB's current DD allocation. R15=0 on success and R15=4 when the valid DCB has no usable/currently allocated DDNAME. Selected fields are JFCBDSNM, JFCBLTYP, JFCBFLSQ, JFCDSORG, JFCRECFM, JFCBLKSI, JFCLRECL, JFCBNVOL, and JFCBVOLS. #COPY $_JFCB supplies the built-in 176-byte DSECT with JFCBLEN=176. Post-OPEN effective values persist across CLOSE for later RDJFCB calls.

$SHOWDCB DCB=dcb,FIELDS=field | (field,...),AREA=address,AREALEN=bytes --- Fields: LRECL | BLKSIZE | DDNAME; R15 status.

$SLEEP seconds | (register) --- Suspend for whole seconds; registers/CC unchanged.

$SRAND (register) --- Seed PRNG. R0 requests host-derived seed; any other GPR supplies its exact 32-bit seed.

$TESTDCB DCB=dcb,RECFM=value | LRECL=value | BLKSIZE=value | DDNAME=name | OPEN=YES | OPEN=NO --- One test; R15 status; success sets CC=0 match / CC=1 no match.

$MODDCB DCB=dcb[,DDNAME=name][,RECFM=value][,LRECL=n][,BLKSIZE=n][,OPENEXIT=address|0] --- Normally changes the closed-DCB baseline. During active OPENEXIT, only RECFM/LRECL/BLKSIZE may be changed; DDNAME or OPENEXIT then causes SYSTEM EEE. Outside the exit, OPENEXIT installs/disables the next OPEN exit. R15: 0 success, 4 open, 8 invalid value, 12 invalid DCB/other.

TIME DEC --- IBM-style local date/time. R0=HHMMSSth; R1=0CYYDDDF. Honors configured timezone/DST.

$VALDATE TYPE=JDATE | GDATE,DATE=operand --- Validate date; R15=0 valid, 4 invalid JDATE, 8 invalid GDATE.

$VALTIME TIME=operand --- Validate HHMMSSth; R15=0 valid, 12 invalid.

$CVTDATE FROMTYPE=JDATE|GDATE|STIME|STCK|STCKE,FROM=operand, TOTYPE=...,TO=operand[,FROMTIME=operand][,TOTIME=operand] --- Convert civil/date/timestamp forms. FROMTIME defaults to midnight for civil-to-timestamp; TOTIME is optional timestamp-to-civil output.

$DAYDIFF jdate1,jdate2 --- R1=signed calendar days jdate1-jdate2; R15 status.

$DAYADJ jdate,signed-days,result --- Add/subtract calendar days; result is JDATE. Range failure R15=20; output unchanged.

$TIMEADJ stime,result[,SECONDS=s][,MINUTES=m][,HOURS=h][,DAYS=d] --- Add elapsed UTC seconds. STIME operands are storage-only; adjustment keywords are signed assembly-time expressions; DAYS=1 is exactly 86400 seconds.

$EXPDATE jdate,area --- Build 37-byte EBCDIC expanded date. Built-in mapping: #COPY $_EXPDATE.

$FMTDATE jdate[,time],FORMAT='literal'|"literal",AREA=area,AREALEN=n or storage format with FORMAT=address,FMTLEN=n --- EBCDIC formatted date/time; TIME defaults midnight; RC 36 area too small, 40 invalid format.

$TIMEUSD , --- R0=CPU time; R1=elapsed time, integer milliseconds; CC unchanged.

$TRACE ON | OFF --- Enable/disable executable runtime tracing.

$WRITE dcb,buffer,length --- Write one physical tape block. R15=status; see §7.

$WRITE dcb,TYPE=TM --- Write one physical tape mark. R15=status; see §7.

ABEND code | (register)[,DUMP][,STEP][,USER | SYSTEM][,REASON=value | (register)] --- Abnormal termination; code low 12 bits. Default USER, no DUMP/STEP, REASON=0. User codes display decimal; system codes hexadecimal.

CLOSE dcb | CLOSE (dcb[,(REWIND|FREE)]...) --- Close DCB(s); flush/complete output as required; R15 status.

FREEMAIN R | RC,LV=value | (register),A=(register) --- Release exact live GETMAIN allocation. R failure is fatal; RC returns nonzero R15.

GET dcb,buffer --- Read one logical record. R15=0 record, 4 EOF, 8 error. If EODAD is supplied, EOF branches there; otherwise RC is returned.

GETMAIN R | RC,LV=value | (register) --- Allocate virtual storage; allocated storage address is returned in R1. R success does not define/clear R15; RC form returns nonzero R15 on allocation failure; R form failure is fatal.

OPEN (dcb[,INPUT | OUTPUT | EXTEND]) [,...] --- Open DCB(s); omitted option = INPUT. R15=0 success; R15=8021 DDNAME not allocated. All other OPEN errors ABEND SYSTEM EEE.

PUT dcb,buffer --- Write one logical record; blocking performed as required; R15 status.

WTO 'message' | WTO text-address,text-length --- Write operator/terminal message; maximum 126 bytes. Linux uses /dev/tty.

WTOR 'message',reply-address,reply-length | WTOR text-address,text-length,reply-address,reply-length --- Write operator/terminal message and read reply; message maximum 126 bytes, reply maximum 119 bytes. Linux uses /dev/tty.

Important register effects: $LINENO→R15 · $RAND→R1 · TIME DEC→R0,R1 · $TIMEUSD→R0,R1 · $DAYDIFF→R1,R15 · $READ→R1,R15 · $CONTROL→R15 · GETMAIN→R1 (and R15 for RC status) · $SHOWDCB/$TESTDCB→R15 · GET/PUT→R15 · OPEN→R15. CC is preserved unless specifically documented.

3. #PRAGMA / Conditional Source

Pragmas occur in the source preamble before the first ordinary source statement; blank/comments do not end the preamble. Trailing + continues long pragmas.

#PRAGMA CODE_LISTING | NO_CODE_LISTING
#PRAGMA RUNTIME_LISTING | NO_RUNTIME_LISTING
#PRAGMA RUNTIME_RC_MESSAGES | NO_RUNTIME_RC_MESSAGES   default ON
#PRAGMA PERFORMANCE | NO_PERFORMANCE                   default OFF
#PRAGMA EXECUTE | NO_EXECUTE
#PRAGMA TRACE | NO_TRACE
#PRAGMA TRACE_ACTIVE                disable with NO_TRACE
#PRAGMA GETMAIN_DEBUG | NO_GETMAIN_DEBUG
#PRAGMA XREF | NO_XREF
#PRAGMA XREF_LONG | NO_XREF_LONG

#PRAGMA TIMEZONE_OFFSET=+HH:MM | -HH:MM     default +00:00
#PRAGMA DST | NO_DST                       default NO_DST
#PRAGMA DST_OFFSET=+HH:MM | -HH:MM         default +01:00
#PRAGMA DST_BEGIN MONTH=n,WEEK=n,DAY=ddd,TIME=HH:MM
#PRAGMA DST_END   MONTH=n,WEEK=n,DAY=ddd,TIME=HH:MM

#PRAGMA LISTING_WIDTH n
#PRAGMA MAX_INSTRUCTIONS n          0 = unlimited; forces PERFORMANCE off
#PRAGMA MAX_SOURCE_DEPTH n
#PRAGMA MAX_CONDITIONAL_DEPTH n
#PRAGMA ABEND_STATUS n
#PRAGMA PARM value
#PRAGMA TRACE_FILE path        (Linux config files only)
#PRAGMA GETMAIN_FILL X'xx'
#PRAGMA DEFINE name[=value]
#DEFINE name[=value]
#UNDEFINE name        removes the active definition; older overridden values do not reappear

TIMEZONE_OFFSET is the base offset added to UTC to obtain local standard time (positive = east/ahead of UTC; negative = west/behind UTC). DST_OFFSET is an additional adjustment applied only while DST is active; it is not an absolute time-zone offset.

Performance: #PRAGMA PERFORMANCE adds an end-of-run summary plus STORAGE, I/O, descending instruction profile, and descending service profile. It also reports after runtime ABEND. TRACE affects timing but not counts.

Conditional source:

#IF expression
#ELIF expression
#ELSE
#ENDIF

Operators: ! | == | != | < | <= | > | >= | && | || | ( ); bare name tests definedness.
Definition precedence: BUILTIN < SYSTEM < PRAGMA < CLI < SOURCE.

#PRAGMA DD ddname,PATH='path'[,RECFM=...][,LRECL=n][,BLKSIZE=n][,TRIM=YES|NO]

#PRAGMA DD,ddname,DATA[,DLM=cc][,RECFM=F|FB|V|VB][,LRECL=n][,BLKSIZE=n]
...data records...
#PRAGMA COMMENT END DATA

#PRAGMA DD,ddname,DUMMY[,RECFM=F|FB|V|VB][,LRECL=n][,BLKSIZE=n]

#PRAGMA DD ddname,UNIT=TAPE,PATH='aws-file',DSN=name,VOL=SER=volser,
           LABEL=SL | NL | BLP[,LBLNO=n][,RECFM=...][,LRECL=n],
           [BLKSIZE=n][,MACRF=...],
           [EXPDT=YYDDD | YYYY/DDD | RETPD=days][,EXPCHK=BYPASS]

4. DCB / Logical I/O

name DCB DSORG=PS,MACRF=R | W | RW | GM | PM,
         DDNAME=ddname[,RECFM=F | V [B] [A | M] | U]
         [,LRECL=n][,BLKSIZE=n][,EODAD=label][,OPENEXIT=address]

DSORG=PS is the only valid DSORG. EODAD is optional for INPUT.

GM | PM = logical GET/PUT processing, including tape blocking/deblocking.
R | W | RW = physical tape $READ/$WRITE interface.
With nonzero OPENEXIT, supplied attributes are merged before the exit and generic defaults are delayed until after BR R14. Entry uses R1=DCB and R14=X'00FFFFFE'. DATA contributes intrinsic FB/80/3280 defaults before the exit; unsupplied PATH/DUMMY/new-tape fields remain zero; existing labeled tape contributes label attributes. While open, $SHOWDCB/$TESTDCB see final effective values; CLOSE restores baseline DCB values while the persistent JFCB retains final OPEN values.

5. AWS Tape Operations

Operation Summary

OPEN INPUT Mount/open selected tape data set for input.

OPEN OUTPUT Mount/open selected tape data set for output.

GET / PUT Logical records; TSDSUTIL handles blocking/deblocking.

$READ / $WRITE Physical blocks; requires MACRF=R | W | RW.

$WRITE ...,TYPE=TM Write physical tape mark in BLP mode.

CLOSE Complete data set; flush blocks/write required tape completion; final close permits unmount.

EOJ/ABEND Open DCBs automatically closed during termination.

Sharing Same PATH/VOLSER shares one mounted volume.

6. Runtime / Operational Notes

• TRACE records instructions/macros and relevant register/storage operands.
• XREF includes symbols, definitions/references, undefined symbols, and optional unreferenced entries.
• Default instruction limit: 10,000,000; zero = unlimited. Limit ABEND: TSDS8028E.
• Self-branch protection ABEND: TSDS8029E.
• GETMAIN debug reports allocation/free activity; fill defaults to X'00'.
• Deferred expression failure TSDS4001E recursively follows deferred EQU chains to root unresolved symbol name(s) when determinable; repeated names are deduplicated. V93 resolves valid deferred EQU chains to a fixed point before reporting failure.
• EX modifies target instruction with the low-order byte of the EX register.
• Linux configuration: /etc/tsdsutil.conf, then $HOME/.config/tsdsutil.conf; CLI/source have higher precedence as defined in the guide.

tsdsutil [options] < source

-h | --help
--execute | --no-execute
--listing=path
--parm=value
--define NAME[=VALUE]
--define=NAME[=VALUE]
--max-instructions=n
--performance | --no-performance
--trace | --trace-active | --no-trace
--trace-file=path
-Lpath | -L path
--ddDDNAME=path                 empty path removes/masks association

7. Physical Tape Return Codes

R15 Meaning

  0 Data block successfully read
  4 Logical EOF for SL/NL
  8 Block longer than buffer; prefix copied, residual discarded
 12 Physical tape mark in BLP mode
 16 Physical end-of-image/EOT
 20 Read attempted after remembered EOT
 24 Invalid operation/state
 28 Tape/host I/O error
 32 Volume/data-set format error
 36 Internal/resource error

R15 Meaning

  0 Success
  8 Block larger than effective BLKSIZE
 20 Operation after EOT, where applicable
 24 Invalid operation/state
 28 Tape/host I/O error
 32 Volume/data-set format error
 36 Internal/resource error

8. Supported S/370 Instructions

Availability list only; consult an IBM S/370 reference for operation/CC details. Do not assume later ESA/390 or z/Architecture instructions are implemented.

A    AH   AL   AR   BAL  BALR BAS  BASR BC   BCR  BCT  BCTR
BXH  BXLE C    CH   CL   CLC  CLI  CLM  CLR  CLCL CR   CS   CDS
CVB  CVD  D    DR   ED   EDMK EX   IC   ICM  L    LA   LCR  LH
LM   LNR  LPR  LR   LTR  M    MH   MR   MVC  MVCL MVI  N    NC
NI   NR   O    OC   OI   OR   S    SH   SLA  SLDA SLL  SLR  SPM
SRA  SRDA SRL  ST   STC  STCK STCKE STH  STM  STCM SVC  TM   TR   TRT
TS   X    XC   XI   XR

Extended branch mnemonics are aliases over BC/BCR.

Quick-reference rule: the current TSDSUTIL User's Guide and implementation govern if this condensed card differs.