Skip to content

Add tooltips for JCL from jes-explorer#377

Draft
1000TurquoisePogs wants to merge 2 commits intofeature/v3/lang-hlasmfrom
feature/v3/lang-jcl
Draft

Add tooltips for JCL from jes-explorer#377
1000TurquoisePogs wants to merge 2 commits intofeature/v3/lang-hlasmfrom
feature/v3/lang-jcl

Conversation

@1000TurquoisePogs
Copy link
Copy Markdown
Member

Proposed changes

This PR adds hover documentation to the existing JCL language mode in the zlux-editor Monaco integration.

JCL source files already had syntax highlighting (the ISPF-style color scheme). This PR adds a hover provider so that placing the cursor over any JCL keyword or parameter name displays a brief description of what it does. No changes are made to the tokenizer or theme.

Changes:

  • webClient/src/app/editor/code-editor/monaco/hiliters/jcl.ts -- added new export JCL_HOVER_DOCS: Record<string, string> containing hover documentation for 60+ JCL keywords, organized into four groups:
    • Statement types: JOB, EXEC, DD, PROC, PEND, IF/THEN/ELSE/ENDIF, INCLUDE, JCLLIB, OUTPUT, SET, CNTL/ENDCNTL, XMIT, COMMAND, EXPORT, SCHEDULE, and JES3 job-group statements (JOBGROUP, ENDGROUP, GJOB, JOBSET, SJOB, ENDSET, AFTER, BEFORE, CONCURRENT).
    • JOB statement parameters: CLASS, MSGCLASS, MSGLEVEL, NOTIFY, REGION, TIME, ADDRSPC, COND, ACCT, TYPRUN, RESTART, BYTES, LINES, PAGES, CARDS, PRTY, PERFORM.
    • EXEC statement parameters: PGM, PARM, DYNAMNBR.
    • DD statement parameters: DSN, DISP, UNIT, VOL, SYSOUT, SPACE, DCB, RECFM, LRECL, BLKSIZE, DSORG, DUMMY, DDNAME, LABEL, BUFNO, FREE, AMP, AVGREC, STORCLAS, MGMTCLAS, DATACLAS, KEYLEN, RKP, EXPDT, RETPD, SUBSYS, PATH, PATHMODE, PATHOPTS, FILEDATA.
  • webClient/src/app/editor/code-editor/monaco/monaco.config.ts -- updated the JCL import to include JCL_HOVER_DOCS and registered a registerHoverProvider('jcl', ...) that resolves the word at the cursor (uppercased) against JCL_HOVER_DOCS. A secondary check extracts parameter names from PARAM= context on the line to handle sub-keywords like RECFM and LRECL.

This PR addresses Issue: zowe/zlux#538

Type of change

  • New feature (non-breaking change which adds functionality)

PR Checklist

  • If the changes in this PR are meant for the next release / mainline, this PR targets the "staging" branch.
  • My code follows the style guidelines of this project (see: Contributing guideline)
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • New and existing unit tests pass locally with my changes
  • video or image is included if visual changes are made
  • Relevant update to CHANGELOG.md
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works, or describe a test method below

Testing

  1. Build the editor plugin and deploy to a Zowe Desktop instance.
  2. Open a JCL file (.jcl or .cntl extension) via the File Explorer. The JCL language mode and ISPF-style color theme should apply as before.
  3. Hover over JCL statement keywords and verify tooltips appear:
    • Hover over JOB on the JOB card -- should show a description of the JOB statement.
    • Hover over EXEC -- should describe the EXEC statement and mention PGM= vs PROC.
    • Hover over DD -- should describe the DD statement and list key parameters.
    • Hover over PROC, PEND, IF, THEN, ELSE, ENDIF -- each should have its own tooltip.
    • Hover over INCLUDE and JCLLIB -- should describe library concatenation.
  4. Hover over DD parameter keywords and verify tooltips:
    • Hover over DSN -- should describe data set naming including &&name and *.
    • Hover over DISP -- should describe status and normal/abnormal disposition values.
    • Hover over SYSOUT -- should describe JES spool output classes.
    • Hover over SPACE -- should describe TRK/CYL allocation syntax.
    • Hover over RECFM, LRECL, BLKSIZE -- each should describe the DCB sub-parameter.
  5. Hover over JOB parameters:
    • Hover over CLASS, MSGCLASS, MSGLEVEL, NOTIFY, REGION, TIME, COND -- each should show a description.
  6. Verify that hovering over non-keyword content (e.g. a data set name, a job name, a comment) produces no tooltip.
  7. Confirm that syntax highlighting and theme are unchanged.

Signed-off-by: 1000TurquoisePogs <sgrady@rocketsoftware.com>
Signed-off-by: 1000TurquoisePogs <sgrady@rocketsoftware.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

Status: Ready for Review

Development

Successfully merging this pull request may close these issues.

1 participant